Guides
How to use the query endpoint with metrics, dimensions, and date ranges
The query endpoint is the core of the Oviond API. It fetches and formats data from any integration using a consistent request/response structure.
POST /v1/integrations/{id}/query Header Value Description Content-Typeapplication/jsonRequest body format AuthorizationBearer oviond_xxxYour Oviond API key (see Authentication ) X-Client-IDCLIENT_IDYour CLIENT ID
Field Type Required Description dataViewstring Yes The data view to query (e.g. "default", "campaigns") metricsstring[] Yes Array of metric IDs to fetch dimensionsstring[] Yes Dimension IDs to group results by dateRangeobject Yes Current and previous date ranges timezonestring Yes IANA timezone (e.g. "UTC", "America/New_York") filtersobject[] No Optional filters to narrow results (GA4, Google Ads, Facebook Ads, Instagram Ads) extraobject No Integration-specific parameters (see Extra Parameters below)
Every query requires both a current and previous date range for comparison:
{ "dateRange" : { "current" : { "startDate" : "2025-01-01" , "endDate" : "2025-01-31" }, "previous" : { "startDate" : "2024-12-01" , "endDate" : "2024-12-31" } } } Dates use YYYY-MM-DD format.
Metrics are the numeric values you want to fetch. Each integration defines its own metric IDs — browse them in the Field Reference .
{ "metrics" : [ "sessions" , "pageviews" , "bounce_rate" ] } Dimensions break down metrics by a category (e.g. by country, by page, by campaign):
{ "dimensions" : [ "country" ] } Some integrations support multiple dimensions in the array:
Google Ads
Meta Ads
Instagram Ads
Google Analytics 4
All query responses use the FormattedResult structure:
{ "success" : true , "data" : { "current" : [ { "date" : "2025-01-01" , "sessions" : 150 , "pageviews" : 420 } ], "currentSummary" : { "sessions" : 4500 , "pageviews" : 12600 }, "previous" : [ { "date" : "2024-12-01" , "sessions" : 130 , "pageviews" : 380 } ], "previousSummary" : { "sessions" : 4100 , "pageviews" : 11200 }, "state" : "ACTIVE" } } The state field indicates:
ACTIVE — data was returned successfullyNO_DATA — query succeeded but no data in rangeERROR — something went wrong
Integrations can have multiple data views representing different data sets. For example, a social media integration might have "posts", "audience", and "stories" data views.
Check available data views for an integration:
curl https://api.oviond.com/v1/integrations/{id} The extra field passes integration-specific parameters that don't fit into the standard metrics, dimensions, filters, or dateRange fields. These are typically entity selections (campaigns, audiences, etc.), view filters, or integration-specific settings.
{ "dataView" : "CAMPAIGNS" , "metrics" : [ "impressions" , "clicks" ], "dimensions" : [ "campaign" ], "dateRange" : { ... }, "extra" : { "campaigns" : [{ "value" : "123" }, { "value" : "456" }], "attribution" : "7d_click" } } Only the integrations listed below use extra. Integrations not listed here ignore it.
Field Type Description attributionstring Attribution model (e.g. "7d_click", "1d_view"). Defaults to account setting. attributionWindowsstring[] Attribution windows. Defaults to ["default"]. campaignsobject[] Filter by campaigns. Each object: { value: "campaign_id" }. adsetsobject[] Filter by ad sets. Each object: { value: "adset_id" }. adsobject[] Filter by ads. Each object: { value: "ad_id" }.
Field Type Description attributionstring Attribution model. Defaults to account setting.
Field Type Description campaignGroupsobject[] Filter by campaign groups. Each object: { value: "group_id" }. campaignsobject[] Filter by campaigns. Each object: { value: "campaign_id" }. adsobject[] Filter by creatives. Each object: { value: "creative_id" }.
Field Type Description campaignsobject[] Filter by campaigns. Each object: { value: "campaign_id" }. adgroupsobject[] Filter by ad groups. Each object: { value: "adgroup_id" }. adsobject[] Filter by ads. Each object: { value: "ad_id" }.
Field Type Description placementstring Ad placement (e.g. "ALL_ON_TWITTER", "PUBLISHER_NETWORK").
Field Type Description searchTypestring Search type: "web", "image", "video", "news". Defaults to "web".
Field Type Description categorystring Lighthouse category (e.g. "performance", "accessibility"). strategystring Device strategy: "desktop" or "mobile". Defaults to "desktop". connectionTypestring Connection type for Chrome UX Report. deviceTypestring Device type for Chrome UX Report.
Field Type Description aggregateboolean Whether to aggregate row data. symbolsobject Symbol mapping for columns.
Field Type Description groupBystring Group analytics by source dimension (e.g. "social", "organic"). Defaults to "none".
Field Type Description regionobject Search engine region. { value: "us" }. Defaults to "us". campaignobject Position tracking campaign. { value: "campaign_id" }.
Field Type Description searchEngineobject Search engine selection. { value: "engine_id" }. keywordobject Keyword filter. { value: "keyword_text" }. competitorobject Competitor filter. { value: "competitor_domain" }. sourceany Data source. typeany Query type. checkany Check configuration. compareany Comparison configuration.
Field Type Description searchEngineobject Search engine. { value: "google_com" }. keywordobject Keyword filter. { value: "keyword_text" }.
Field Type Description campaignobject Filter to a specific campaign. { value: "campaign_id" }. audienceobject Filter to a specific audience/list. { value: "list_id" }. automationobject Filter to a specific automation. { value: "automation_id" }. interestCategoryobject Interest category for audience interests. { value: "category_id" }. interestobject Specific interest within a category. { value: "interest_id" }. campaignClickobject Campaign link click filter. { value: "link_id" }.
Field Type Description campaignsobject[] Filter by campaigns. Each object: { value: "campaign_id" }. listsobject[] Filter by subscriber lists. Each object: { value: "list_id" }. journeysobject[] Filter by journeys. Each object: { value: "journey_id" }.
Field Type Description campaignsobject[] Filter by campaigns (future use). flowsobject[] Filter by flows (future use).
Field Type Description newslettersobject[] Filter by newsletters/campaigns. Each object: { value: "newsletter_id" }.
Field Type Description viewobject Filter to a specific video. { value: "video_id" }.
Field Type Description viewobject Filter to specific media. { value: "media_id" }. mediaSurfacesstring[] Filter media by type (e.g. ["FEED"]). hashtagstring Hashtag to search. hashtagTypestring Hashtag search type: "recent_media" or "top_media". Defaults to "recent_media".
Field Type Description companystring Filter calls by company ID.
Field Type Description viewobject Select a specific alert. { value: "alert_id" }.
Field Type Description viewobject Filter to a specific video. { value: "video_id" }.
Field Type Description viewobject Filter to a specific media. { value: "media_id" }.
Field Type Description viewobject Filter to a specific campaign. { value: "campaign_id" }.
Field Type Description viewobject View filter. { value: "form_id" }.
Field Type Description viewobject View filter. { value: "campaign_id" }.
Field Type Description viewobject Select a to-do list. { value: "todolist_id" }.
Field Type Description statusstring Order status filter (e.g. "completed", "processing").
Field Type Description businessCategorystring Business category for benchmarks. Defaults to "OTHER".
Field Type Description statusstring Opportunity/contact status filter. Defaults to "all".
