{ "openapi": "3.1.0", "info": { "title": "Reporting Ninja API", "version": "1.0.0", "description": "Reporting Ninja public REST API including [OpenAPI spec](/api/v1/openapi.json). Query your marketing data across 22 integrations including paid social, paid search, organic social, web analytics, search console and CRM. All endpoints require Bearer authentication and return JSON envelopes following the schemas below.\n\n## Error envelope and `error_code`\n\nEvery error response carries a machine-readable `error_code` (UPPER_SNAKE_CASE) in addition to a human-readable `message`. Clients should switch on `error_code` for error handling instead of parsing the message text. See `components/schemas/ErrorEnvelope` for the full enum.\n\n## HTTP status codes\n\nMost responses use **HTTP 200** with `envelope.status = \"ok\" | \"error\"`. The exceptions are:\n\n- **HTTP 401** when the Bearer token is missing or invalid (`error_code: AUTH_INVALID`).\n- **HTTP 429** when the rate limit is exceeded, with a `Retry-After` header (`error_code: RATE_LIMITED`).\n\nFor validation errors (missing fields, invalid values, unknown integration, etc.) the response is HTTP 200 with `status = \"error\"` and a specific `error_code`. The HTTP status code alone is NOT sufficient to discriminate success from validation failure -- always read `envelope.status` and `envelope.error_code`.\n\n## Rate limit\n\nAll endpoints share a per-API-key rate limit: **300 requests/minute AND 5000 requests/day**. Both limits apply simultaneously. When exceeded the response is **HTTP 429** with a `Retry-After` header (seconds until the more-restrictive window resets) and the standard error envelope. The `X-RateLimit-*` headers are present on every response (success or 429):\n\n- `X-RateLimit-Limit`: per-minute cap (currently 300)\n- `X-RateLimit-Remaining`: requests remaining in the current minute window\n- `X-RateLimit-Reset`: unix epoch seconds when the minute window resets\n- `X-RateLimit-Limit-Day`: per-day cap (currently 5000)\n- `X-RateLimit-Remaining-Day`: requests remaining today\n- `X-RateLimit-Reset-Day`: unix epoch seconds when the day window resets", "contact": { "name": "Reporting Ninja support", "url": "https://www.reportingninja.com/" } }, "servers": [ { "url": "https://api.reportingninja.com/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Integrations", "description": "List available integrations and inspect their data views, settings and filter catalog." }, { "name": "Connections", "description": "List the consumer's authorized connections (e.g. Meta accounts) per integration." }, { "name": "Fields", "description": "List the dimensions and metrics available for a given connection." }, { "name": "Query", "description": "Execute data queries synchronously or asynchronously." } ], "paths": { "/integrations": { "post": { "operationId": "listIntegrations", "tags": [ "Integrations" ], "summary": "List available integrations", "description": "Returns the set of integrations exposed by the public API. The catalog grows incrementally; check this endpoint to discover which integrations are available before calling /integrations/detail, /connections, /fields or /query.", "x-mcp-description": "Use this tool to discover which marketing data sources (integration_ids) are available before calling /connections, /fields or /query. The response is a stable list of id + name; it does not include the full configuration of each integration. To get that, call /integrations/detail.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyBody" }, "example": {} } } }, "responses": { "200": { "description": "OK or business error envelope.", "content": { "application/json": { "examples": { "ok": { "value": { "status": "ok", "data": { "integrations": [ { "id": "facebook_ads", "name": "Meta Ads" }, { "id": "google_ads", "name": "Google Ads" }, { "id": "ga4", "name": "Google Analytics 4" }, { "id": "microsoft_ads", "name": "Microsoft Ads" }, { "id": "youtube", "name": "YouTube" }, { "id": "google_search_console", "name": "Google Search Console" }, { "id": "google_business_profile", "name": "Google Business Profile" }, { "id": "facebook_insights", "name": "Facebook Insights" }, { "id": "instagram_insights", "name": "Instagram Insights" }, { "id": "linkedin_ads", "name": "LinkedIn Ads" }, { "id": "linkedin_pages", "name": "LinkedIn Pages" }, { "id": "tiktok_ads", "name": "TikTok Ads" }, { "id": "tiktok_organic", "name": "TikTok Organic" }, { "id": "pinterest_ads", "name": "Pinterest Ads" }, { "id": "pinterest_organic", "name": "Pinterest Organic" }, { "id": "snapchat_ads", "name": "Snapchat Ads" }, { "id": "reddit_ads", "name": "Reddit Ads" }, { "id": "twitter_analytics", "name": "Twitter Analytics" }, { "id": "twitter_ads", "name": "Twitter Ads" }, { "id": "mailchimp", "name": "Mailchimp" }, { "id": "cross_platform", "name": "Cross-platform" }, { "id": "hubspot", "name": "HubSpot" } ] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/integrations/detail": { "post": { "operationId": "getIntegrationDetail", "tags": [ "Integrations" ], "summary": "Get integration details", "description": "Returns the full configuration for one integration: data views (if any), settings (e.g. attribution_window for facebook_ads) and the filter catalog (fields and allowed operators per field).", "x-mcp-description": "Use this tool when you need the precise filter field IDs, allowed operators and settings keys for an integration. The catalog returned here is the contract for /v1/query: field_ids you can request, filters you can apply, settings you can override. The response is the single source of truth for what is queryable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDetailRequest" }, "example": { "integration_id": "facebook_ads" } } } }, "responses": { "200": { "description": "OK or business error envelope.", "content": { "application/json": { "examples": { "ok_facebook_ads": { "summary": "facebook_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "facebook_ads", "name": "Meta Ads", "category": "paid_social", "supports_custom_fields_per_account": true, "data_views": null, "settings": [ { "id": "attribution_window", "name": "Attribution window", "recommended_value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_7D", "options": [ { "value": "ATTRIBUTION_MODEL_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_7D", "label": "7 days after click" }, { "value": "ATTRIBUTION_MODEL_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_1D", "label": "1 day after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_7D", "label": "1 day after view + 7 days after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_1D", "label": "1 day after view + 1 day after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_7D###CLICK_ATTRIBUTION_WINDOW_7D", "label": "7 days after view + 7 days after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_7D###CLICK_ATTRIBUTION_WINDOW_1D", "label": "7 days after view + 1 day after click" }, { "value": "ATTRIBUTION_MODEL_VIEW###VIEW_ATTRIBUTION_WINDOW_7D###CLICK_ATTRIBUTION_WINDOW_7D", "label": "7 days after view" }, { "value": "ATTRIBUTION_MODEL_VIEW###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_7D", "label": "1 day after view" }, { "value": "ATTRIBUTION_MODEL_VIEW###VIEW_SKAN_ATTRIBUTION###CLICK_ATTRIBUTION_WINDOW_7D", "label": "SKAdNetwork - View-through" }, { "value": "ATTRIBUTION_MODEL_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_SKAN_ATTRIBUTION", "label": "SKAdNetwork - Click-through" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_28D", "label": "1 day after view + 28 days after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_7D###CLICK_ATTRIBUTION_WINDOW_28D", "label": "7 days after view + 28 days after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_28D###CLICK_ATTRIBUTION_WINDOW_28D", "label": "28 days after view + 28 days after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_28D###CLICK_ATTRIBUTION_WINDOW_7D", "label": "28 days after view + 7 days after click" }, { "value": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_28D###CLICK_ATTRIBUTION_WINDOW_1D", "label": "28 days after view + 1 day after click" }, { "value": "ATTRIBUTION_MODEL_VIEW###VIEW_ATTRIBUTION_WINDOW_28D###CLICK_ATTRIBUTION_WINDOW_28D", "label": "28 days after view" }, { "value": "ATTRIBUTION_MODEL_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_28D", "label": "28 days after click" } ] } ], "filters": { "supported": true, "combination": "and", "fields": [ { "id": "campaign.name", "name": "Campaign name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "campaign.effective_status", "name": "Campaign status", "category": "status", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "PAUSED", "DELETED", "PENDING_REVIEW", "DISAPPROVED", "PREAPPROVED", "PENDING_BILLING_INFO", "CAMPAIGN_PAUSED", "ARCHIVED", "ADSET_PAUSED" ] } ], "note": "The 3 status fields (campaign.effective_status, adset.effective_status, ad.effective_status) share the same allowed_values list. Invalid values are rejected upfront with a clear error envelope before any call to the Graph API." } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } }, "ok_google_ads": { "summary": "google_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "google_ads", "name": "Google Ads", "category": "paid_search", "supports_custom_fields_per_account": false, "data_views": [ { "id": "campaign", "name": "Campaign" }, { "id": "ad_group", "name": "Ad group" }, { "id": "keyword_view", "name": "Keyword" } ], "settings": null, "filters": { "supported": true, "combination": "and", "fields": [ { "id": "campaign.id", "name": "Campaign ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS", "IN", "NOT_IN" ] }, { "id": "campaign.name", "name": "Campaign name", "category": "string", "operators": [ "EQUALS", "NOT_EQUALS", "LIKE", "NOT_LIKE", "IN", "NOT_IN", "REGEXP_MATCH", "NOT_REGEXP_MATCH" ] }, { "id": "campaign.status", "name": "Campaign status", "category": "enum", "operators": [ "IN", "NOT_IN" ] }, { "id": "campaign.labels", "name": "Campaign labels", "category": "label", "operators": [ "CONTAINS_ANY", "CONTAINS_ALL", "CONTAINS_NONE" ] }, { "id": "metrics.clicks", "name": "Clicks", "category": "metric", "operators": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL" ] }, { "id": "metrics.cost_micros", "name": "Cost (in account currency)", "category": "metric", "operators": [ "EQUALS", "NOT_EQUALS", "GREATER_THAN", "GREATER_THAN_OR_EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL" ] } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } }, "ok_ga4": { "summary": "ga4 detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "ga4", "name": "Google Analytics 4", "category": "analytics", "supports_custom_fields_per_account": true, "notes": [ "Metrics of the `percent` field_type are returned in 0-100 scale (raw GA4 API), not normalized to 0-1. Divide by 100 client-side if a 0-1 representation is needed." ], "data_views": null, "settings": null, "filters": { "supported": true, "combination": "and_or", "note": "Filter fields are DYNAMIC: use /v1/fields to discover the fields available for a connection+account (predefined + per-property custom dimensions/metrics). Each filter MUST include `type_of_field` (\"dimension\" or \"metric\") and MAY include `combination` (\"AND\" by default, or \"OR\"). Dimension fields use dimension_operators; metric fields use metric_operators (see the two lists below). For IN_LIST / NOT_IN_LIST the value MAY be an array; individual values must NOT contain commas. For metric filters the value MUST be numeric. Current limitations: (a) all filters in a single request must share the same type_of_field (mixed dimension+metric not supported yet); (b) when 2 or more filters are sent, the combination of the second filter defines the combination of the whole group (combinations of other positions are ignored, including the combination of a single-filter request)." } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_microsoft_ads": { "summary": "microsoft_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "microsoft_ads", "name": "Microsoft Ads", "category": "paid_search", "supports_custom_fields_per_account": false, "data_views": [ { "id": "account_performance", "name": "Account performance" }, { "id": "campaign_performance", "name": "Campaign performance" }, { "id": "ad_performance", "name": "Ad performance" }, { "id": "ad_extension_detail", "name": "Ad extension detail" }, { "id": "keyword_performance", "name": "Keyword performance" }, { "id": "search_query_performance", "name": "Search query performance" }, { "id": "geographic_performance", "name": "Geographic performance" }, { "id": "age_gender_audience", "name": "Age gender audience" }, { "id": "product_dimension_performance", "name": "Product dimension performance" }, { "id": "call_detail", "name": "Call detail" }, { "id": "goals_and_funnels", "name": "Goals and funnels" } ], "settings": null, "filters": { "supported": true, "combination": "and", "note": "Filter fields availability depends on the data_view. For each field, the `data_views` array declares the data_views where it can be used. Some fields have a closed list of allowed values (`allowed_values`); if present, the filter value MUST belong to this list (values are SCREAMING_SNAKE_CASE enum names, e.g. ACTIVE, SMART_PHONE, SEARCH -- not the display strings). IN_LIST accepts an array of values; CONTAINS / NOT_CONTAINS accept a scalar string. Current limitations: (a) only AND combination is supported (the `combination` attribute is NOT accepted on filters); (b) `type_of_field` must not be included in YouTube filter requests; all YouTube filter fields are dimensions; (c) IN_LIST on free-text array-of-string fields (Keyword, SearchQuery, Country, Language) is forwarded to the Bing Ads Reporting API but the API may silently ignore it or require an exact match against an internal format -- if you need strict filtering on those fields, validate the result row-by-row client-side.", "fields": [ { "id": "AdDistribution", "name": "Ad distribution", "category": "enum", "operators": [ "IN_LIST" ], "allowed_values": [ "Search", "Audience", "Content" ], "data_views": [ "account_performance", "campaign_performance", "ad_performance", "keyword_performance", "geographic_performance", "age_gender_audience", "goals_and_funnels" ] }, { "id": "CampaignStatus", "name": "Campaign status", "category": "enum", "operators": [ "IN_LIST" ], "allowed_values": [ "Active", "Paused", "Deleted" ], "data_views": [ "campaign_performance", "search_query_performance", "geographic_performance", "age_gender_audience" ] }, { "id": "CampaignName", "name": "Campaign name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "data_views": [ "campaign_performance", "ad_performance", "ad_extension_detail", "keyword_performance", "search_query_performance", "product_dimension_performance", "goals_and_funnels" ] }, { "id": "Keyword", "name": "Keyword", "category": "string", "operators": [ "IN_LIST" ], "data_views": [ "keyword_performance" ] } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_youtube": { "summary": "youtube detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "youtube", "name": "YouTube", "category": "video_analytics", "supports_custom_fields_per_account": false, "notes": [ "Data freshness: the YouTube Analytics API publishes per-day stats 4-5 days after the actual date, so the most recent 4-5 days of any date_range typically return zero or partial values." ], "data_views": [ { "id": "basic", "name": "Basic stats" }, { "id": "lifetime", "name": "Lifetime stats" }, { "id": "geographic", "name": "User geography" }, { "id": "playback_details", "name": "Playback details" }, { "id": "playback_locations", "name": "Playback locations" }, { "id": "traffic_sources", "name": "Traffic sources" }, { "id": "device_and_os", "name": "Device type and operating system" }, { "id": "viewer_demographics", "name": "Viewer demographics" }, { "id": "content_sharing", "name": "Content sharing" }, { "id": "audience_retention", "name": "Audience retention" }, { "id": "top_videos", "name": "Top videos" }, { "id": "playlist_basic", "name": "Basic playlist stats" }, { "id": "top_playlists", "name": "Top playlists" } ], "settings": null, "filters": { "supported": true, "combination": "and", "note": "Filter fields availability depends on the data_view. For each field, the `data_views` array declares the data_views where it can be used. Four fields have a closed list of allowed values (`allowed_values`); if present, the filter value MUST belong to this list (case-sensitive). `country` accepts ISO 3166-1 alpha-2 country codes (a few legacy codes also accepted); invalid codes are rejected by the server before reaching the YouTube API. `videoId` and `playlistId` are YouTube resource IDs (free-text). Multi-value support: only `videoId` and `playlistId` accept multi-value IN_LIST (comma-separated OR semantics, native YouTube Analytics behavior for ID-list dimensions). All other fields (`country`, `subscribedStatus`, `liveOrOnDemand`, `youtubeProduct`, `insightTrafficSourceType`, `audienceType`) are single-value-only per filter -- YouTube Analytics API rejects multi-value on them with HTTP 400 \"Invalid value\". Use IN_LIST with a 1-element array or a scalar value for these. Only the IN_LIST operator is exposed (YouTube Analytics API only supports equality semantics). Individual filter values MUST NOT contain a comma (reserved as multi-value separator). `data_view: audience_retention` REQUIRES a filter on `videoId`. Current limitations: only AND combination is supported between distinct filter fields (the `combination` attribute is NOT accepted on filters); `type_of_field` must not be included in YouTube filter requests; all YouTube filter fields are dimensions.", "fields": [ { "id": "country", "name": "Country", "category": "string", "operators": [ "IN_LIST" ], "data_views": [ "basic", "playback_details", "playback_locations", "traffic_sources", "device_and_os", "viewer_demographics", "content_sharing", "top_videos", "playlist_basic", "top_playlists" ] }, { "id": "videoId", "name": "Video ID", "category": "id", "operators": [ "IN_LIST" ], "data_views": [ "basic", "geographic", "playback_details", "playback_locations", "traffic_sources", "device_and_os", "viewer_demographics", "content_sharing", "audience_retention" ] }, { "id": "subscribedStatus", "name": "Subscribed status", "category": "enum", "operators": [ "IN_LIST" ], "allowed_values": [ "SUBSCRIBED", "UNSUBSCRIBED" ], "data_views": [ "playback_details", "playback_locations", "traffic_sources", "device_and_os", "viewer_demographics", "content_sharing", "audience_retention", "playlist_basic", "top_playlists" ] }, { "id": "insightTrafficSourceType", "name": "Traffic source type", "category": "enum", "operators": [ "IN_LIST" ], "allowed_values": [ "ADVERTISING", "EXT_URL", "RELATED_VIDEO", "SUBSCRIBER", "YT_CHANNEL", "YT_OTHER_PAGE", "YT_SEARCH" ], "data_views": [ "traffic_sources" ] } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_google_search_console": { "summary": "google_search_console detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "google_search_console", "name": "Google Search Console", "category": "seo", "supports_custom_fields_per_account": false, "notes": [ "Data freshness: the Search Console API publishes per-day data 2-3 days after the actual date, so the most recent 2-3 days of any date_range typically return zero or partial values.", "Each /v1/query request must include at least one metric and at most one dimension in the fields[] array (Search Console API constraint)." ], "data_views": null, "settings": [ { "id": "search_type", "name": "Search type", "recommended_value": "web", "options": [ { "value": "web", "label": "Web search" }, { "value": "image", "label": "Image search" }, { "value": "video", "label": "Video search" }, { "value": "news", "label": "News search" } ] } ], "filters": { "supported": true, "combination": "and", "note": "Filter fields: country, device, page, query (searchAppearance and date are NOT filterable). country accepts ISO 3166-1 alpha-3 LOWERCASE codes (e.g. usa, esp, fra) -- different from other integrations; invalid codes are rejected by the upstream Search Console API. device has a closed list of allowed_values. page and query are free-text. Each filter is a single value (the Search Console API does not support OR multi-value within a filter natively). Only AND combination is supported between distinct filter fields. type_of_field is NOT accepted as input (derived internally as dimension); combination is NOT accepted as input.", "fields": [ { "id": "country", "name": "Country", "category": "string", "operators": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "NOT_CONTAINS" ] }, { "id": "device", "name": "Device", "category": "enum", "operators": [ "EQUALS", "NOT_EQUALS" ], "allowed_values": [ "DESKTOP", "MOBILE", "TABLET" ] }, { "id": "page", "name": "Page", "category": "string", "operators": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "NOT_CONTAINS" ] }, { "id": "query", "name": "Query", "category": "string", "operators": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "NOT_CONTAINS" ] } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_google_business_profile": { "summary": "google_business_profile detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "google_business_profile", "name": "Google Business Profile", "category": "local_seo", "supports_custom_fields_per_account": false, "notes": [ "Data freshness: the Business Profile Performance API publishes per-day stats 3-4 days after the actual date, so the most recent 3-4 days of any date_range typically return zero or partial values." ], "data_views": [ { "id": "performance", "name": "Performance" }, { "id": "search_terms", "name": "Search terms" }, { "id": "reviews_timebound", "name": "Reviews (timebound)" }, { "id": "reviews_lifetime", "name": "Reviews (lifetime)" } ], "settings": null, "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_facebook_insights": { "summary": "facebook_insights detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "facebook_insights", "name": "Facebook Insights", "category": "organic_social", "supports_custom_fields_per_account": false, "notes": [ "Meta Graph API limitations apply unchanged: FANS metrics (page_fans, page_fans_city, ...) require period=day; post metrics with breakdown are omitted upstream." ], "data_views": [ { "id": "page", "name": "Page" }, { "id": "post", "name": "Post" }, { "id": "post_aggregated", "name": "Post (aggregated)" }, { "id": "reel", "name": "Reel" }, { "id": "reel_aggregated", "name": "Reel (aggregated)" } ], "settings": null, "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_instagram_insights": { "summary": "instagram_insights detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "instagram_insights", "name": "Instagram Insights", "category": "organic_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "account", "name": "Account" }, { "id": "posts", "name": "Posts" }, { "id": "posts_aggregated", "name": "Aggregated figures from posts in period" } ], "settings": null, "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_linkedin_ads": { "summary": "linkedin_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "linkedin_ads", "name": "LinkedIn Ads", "category": "paid_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "account", "name": "Account" }, { "id": "campaign_group", "name": "Campaign group" }, { "id": "campaign", "name": "Campaign" }, { "id": "creative", "name": "Creative" }, { "id": "conversion", "name": "Conversion" } ], "settings": null, "filters": { "supported": true, "combination": "or", "note": "All filter fields are dimensions; type_of_field='dimension' is REQUIRED in each filter (metric filters are not supported). LinkedIn Marketing API only supports OR combination between filters: combination='OR' (default if absent) is accepted; combination='AND' is rejected upfront with a clear error. For multi-value filters (IN/NOT_IN) provide a comma-separated string in `value` (e.g. \"ACTIVE,PAUSED\"). enum fields with `allowed_values` MUST receive one of the listed values; invalid values are rejected upfront.", "fields": [ { "id": "campaignGroupId", "name": "Campaign group ID", "category": "id", "type_of_field": "dimension", "operators": [ "EQUALS", "NOT_EQUALS" ] }, { "id": "campaignId", "name": "Campaign ID", "category": "id", "type_of_field": "dimension", "operators": [ "EQUALS", "NOT_EQUALS" ] }, { "id": "creativeId", "name": "Creative ID", "category": "id", "type_of_field": "dimension", "operators": [ "EQUALS", "NOT_EQUALS" ] }, { "id": "campaignGroupName", "name": "Campaign group name", "category": "name", "type_of_field": "dimension", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "campaignName", "name": "Campaign name", "category": "name", "type_of_field": "dimension", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "creativeName", "name": "Creative name", "category": "name", "type_of_field": "dimension", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "campaignGroupStatus", "name": "Campaign group status", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "ARCHIVED", "CANCELED", "COMPLETED", "DRAFT", "PAUSED" ] }, { "id": "campaignStatus", "name": "Campaign status", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "ARCHIVED", "CANCELED", "COMPLETED", "DRAFT", "PAUSED" ] }, { "id": "campaignType", "name": "Campaign type", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "TEXT_AD", "SPONSORED_UPDATES", "SPONSORED_INMAILS", "DYNAMIC" ] }, { "id": "creativeStatus", "name": "Creative status", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "ARCHIVED", "CANCELED", "PAUSED", "DRAFT" ] }, { "id": "creativeType", "name": "Creative type", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "TEXT_AD", "IMAGE_AD", "VIDEO_AD", "ARTICLE_AD", "LIVE_VIDEO", "CAROUSEL_AD", "DOCUMENT_AD", "JOBS_AD", "SPOTLIGHT_AD", "FOLLOWER_AD", "EVENT_AD", "MESSAGE_AD", "CONVERSATION_AD" ] } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_linkedin_pages": { "summary": "linkedin_pages detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "linkedin_pages", "name": "LinkedIn Pages", "category": "organic_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "lifetime_followers", "name": "Lifetime follower statistics breakdown" }, { "id": "timebound_follower_gains", "name": "Time-bound follower gains statistics" }, { "id": "realtime_followers", "name": "Real-time follower count" }, { "id": "timebound_share", "name": "Time-bound aggregated posts statistics" }, { "id": "specific_shares", "name": "Time-bound specific posts statistics" }, { "id": "lifetime_org_page", "name": "Lifetime organization page statistics breakdown" }, { "id": "timebound_org_page", "name": "Time-bound organization page statistics" } ], "settings": null, "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_tiktok_ads": { "summary": "tiktok_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "tiktok_ads", "name": "TikTok Ads", "category": "paid_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "audience", "name": "Audience" }, { "id": "account", "name": "Account" }, { "id": "campaign", "name": "Campaign" }, { "id": "ad_group", "name": "Ad group" }, { "id": "ad", "name": "Ad" } ], "settings": null, "filters": { "supported": true, "combination": "or", "note": "All filter fields are dimensions; type_of_field='dimension' is REQUIRED in each filter (metric filters are not supported). TikTok Marketing API only supports OR combination between filters: combination='OR' (default if absent) is accepted; combination='AND' is rejected upfront with a clear error. For multi-value filters (IN/NOT_IN) provide a comma-separated string in `value` (e.g. 'ENABLE,DISABLE'). enum fields with `allowed_values` MUST receive one of the listed values; invalid values are rejected upfront. AUDIENCE data_view scopes the fields to those with audience-specific report types; ADVERTISER/CAMPAIGN/ADGROUP/AD data_views scope to the corresponding level.", "fields": [ { "id": "campaign_id", "name": "Campaign ID", "category": "id", "type_of_field": "dimension", "operators": [ "EQUALS", "NOT_EQUALS" ] }, { "id": "adgroup_id", "name": "Ad group ID", "category": "id", "type_of_field": "dimension", "operators": [ "EQUALS", "NOT_EQUALS" ] }, { "id": "ad_id", "name": "Ad ID", "category": "id", "type_of_field": "dimension", "operators": [ "EQUALS", "NOT_EQUALS" ] }, { "id": "campaign_name", "name": "Campaign name", "category": "name", "type_of_field": "dimension", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "adgroup_name", "name": "Ad group name", "category": "name", "type_of_field": "dimension", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "ad_name", "name": "Ad name", "category": "name", "type_of_field": "dimension", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "ad_text", "name": "Ad text", "category": "name", "type_of_field": "dimension", "operators": [ "CONTAINS", "NOT_CONTAINS" ] }, { "id": "campaign_type", "name": "Campaign type", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "REGULAR_CAMPAIGN", "IOS14_CAMPAIGN" ] }, { "id": "campaign_budget_mode", "name": "Campaign budget mode", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "BUDGET_MODE_DAY", "BUDGET_MODE_TOTAL", "BUDGET_MODE_INFINITE" ] }, { "id": "campaign_operation_status", "name": "Campaign status", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "DISABLE", "ENABLE" ] }, { "id": "objective_type", "name": "Objective type", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "APP_INSTALL", "CONVERSIONS", "REACH", "TRAFFIC", "VIDEO_VIEWS", "SHOP_PURCHASES" ] }, { "id": "adgroup_budget_mode", "name": "Ad group budget mode", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "BUDGET_MODE_DAY", "BUDGET_MODE_TOTAL", "BUDGET_MODE_INFINITE" ] }, { "id": "adgroup_operation_status", "name": "Ad group status", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "DISABLE", "ENABLE", "FROZEN" ] }, { "id": "optimization_goal", "name": "Optimization goal", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "CLICK", "CONVERT", "INSTALL", "IN_APP_EVENT", "SHOW", "REACH", "LEAD_GENERATION", "FOLLOWERS", "PROFILE_VIEWS", "VALUE", "MT_LIVE_ROOM", "PRODUCT_CLICK_IN_LIVE", "ENGAGED_VIEW", "ENGAGED_VIEW_FIFTEEN" ] }, { "id": "bid_type", "name": "Bid type", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "BID_TYPE_CUSTOM", "BID_TYPE_NO_BID" ] }, { "id": "ad_operation_status", "name": "Ad status", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "DISABLE", "ENABLE", "FROZEN" ] }, { "id": "ad_format", "name": "Ad format", "category": "enum", "type_of_field": "dimension", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "SINGLE_IMAGE", "SINGLE_VIDEO", "CAROUSEL", "LIVE_CONTENT" ] } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_tiktok_organic": { "summary": "tiktok_organic detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "tiktok_organic", "name": "TikTok Organic", "category": "organic_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "profile", "name": "Profile" }, { "id": "audience", "name": "Audience" }, { "id": "video", "name": "Video" } ], "settings": null, "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_pinterest_ads": { "summary": "pinterest_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "pinterest_ads", "name": "Pinterest Ads", "category": "paid_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "account", "name": "Account" }, { "id": "campaign", "name": "Campaign" }, { "id": "ad_group", "name": "Ad group" }, { "id": "ad", "name": "Ad" } ], "settings": [ { "id": "click_window", "name": "Click attribution window", "description": "Days after a click counted for conversions.", "recommended_value": "30", "options": [ { "value": "1", "label": "1 day" }, { "value": "7", "label": "7 days" }, { "value": "30", "label": "30 days" }, { "value": "60", "label": "60 days" } ] }, { "id": "engagement_window", "name": "Engagement attribution window", "description": "Days after an engagement counted for conversions.", "recommended_value": "30", "options": [ { "value": "1", "label": "1 day" }, { "value": "7", "label": "7 days" }, { "value": "30", "label": "30 days" }, { "value": "60", "label": "60 days" } ] }, { "id": "view_window", "name": "View attribution window", "description": "Days after a view counted for conversions.", "recommended_value": "1", "options": [ { "value": "1", "label": "1 day" }, { "value": "7", "label": "7 days" }, { "value": "30", "label": "30 days" }, { "value": "60", "label": "60 days" } ] }, { "id": "conversion_report_time", "name": "Conversion report time", "description": "Whether conversions are reported by the date of the ad event or the date of the conversion event.", "recommended_value": "TIME_OF_AD_ACTION", "options": [ { "value": "TIME_OF_AD_ACTION", "label": "Date of ad event" }, { "value": "TIME_OF_CONVERSION", "label": "Date of conversion event" } ] } ], "filters": { "supported": true, "combination": "or", "note": "All filter fields are dimensions; type_of_field='dimension' is REQUIRED in each filter (metric filters are not supported). Pinterest Marketing API v5 only applies OR combination between filter conditions: combination='OR' (default if absent) is accepted; combination='AND' is rejected upfront with a clear error. For multi-value filters (IN/NOT_IN) provide a comma-separated string in `value` (e.g. 'ACTIVE,PAUSED'). enum fields with `allowed_values` MUST receive one of the listed values; invalid values are rejected upfront. Filter applicability depends on the resolved data_view: CAMPAIGN_* filters apply when data_view=campaign|ad_group|ad; AD_GROUP_* filters apply when data_view=ad_group|ad; AD_* and CREATIVE_TYPE filters apply when data_view=ad. The API returns an explicit error if an inapplicable filter is submitted.", "fields": [ { "id": "CAMPAIGN_ID", "name": "Campaign ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "AD_GROUP_ID", "name": "Ad group ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "AD_ID", "name": "Ad ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "CAMPAIGN_NAME", "name": "Campaign name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "AD_GROUP_NAME", "name": "Ad group name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "AD_NAME", "name": "Ad name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "CAMPAIGN_STATUS", "name": "Campaign status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "PAUSED", "ARCHIVED" ], "type_of_field": "dimension" }, { "id": "OBJECTIVE_TYPE", "name": "Objective type", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "AWARENESS", "CONSIDERATION", "VIDEO_VIEW", "WEB_CONVERSION", "CATALOG_SALES", "WEB_SESSIONS", "AWARENESS_RESERVED", "ENGAGEMENT" ], "type_of_field": "dimension" }, { "id": "AD_GROUP_STATUS", "name": "Ad group status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "PAUSED", "ARCHIVED" ], "type_of_field": "dimension" }, { "id": "AD_GROUP_SUMMARY_STATUS", "name": "Ad group summary status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "RUNNING", "PAUSED", "NOT_STARTED", "COMPLETED", "ADVERTISER_DISABLED", "ARCHIVED" ], "type_of_field": "dimension" }, { "id": "AD_STATUS", "name": "Ad status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "PAUSED", "ARCHIVED" ], "type_of_field": "dimension" }, { "id": "AD_SUMMARY_STATUS", "name": "Ad summary status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "APPROVED", "PAUSED", "PENDING", "REJECTED", "ADVERTISER_DISABLED", "ARCHIVED" ], "type_of_field": "dimension" }, { "id": "AD_REVIEW_STATUS", "name": "Ad review status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "OTHER", "PENDING", "REJECTED", "APPROVED" ], "type_of_field": "dimension" }, { "id": "CREATIVE_TYPE", "name": "Creative type", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "REGULAR", "VIDEO", "SHOPPING", "CAROUSEL", "MAX_VIDEO", "SHOP_THE_PIN", "STORY" ], "type_of_field": "dimension" } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_pinterest_organic": { "summary": "pinterest_organic detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "pinterest_organic", "name": "Pinterest Organic", "category": "organic_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "profile_lifetime", "name": "Profile (lifetime)" }, { "id": "profile_timebound", "name": "Profile (time-bound)" }, { "id": "top_pins", "name": "Top pins" }, { "id": "top_video_pins", "name": "Top video pins" } ], "settings": [ { "id": "pinterest_source", "name": "Source", "description": "Whether the pin is owned by the user or by other users.", "applies_to_data_views": [ "profile_timebound", "top_pins", "top_video_pins" ], "recommended_value": "ALL", "options": [ { "value": "ALL", "label": "All" }, { "value": "YOUR_PINS", "label": "Your pins" }, { "value": "OTHER_PINS", "label": "Other pins" } ] }, { "id": "pinterest_claimed_content", "name": "Claimed content", "description": "Whether the pin links to a website claimed by the user, by other users, or both.", "applies_to_data_views": [ "profile_timebound", "top_pins", "top_video_pins" ], "recommended_value": "BOTH", "options": [ { "value": "BOTH", "label": "Both" }, { "value": "CLAIMED", "label": "Claimed" }, { "value": "OTHER", "label": "Other" } ] }, { "id": "pinterest_sort_by", "name": "Top pins by", "description": "Metric to sort by. The allowed values depend on the data_view (top_pins exposes 5 values; top_video_pins exposes 9 video-specific values).", "applies_to_data_views": [ "top_pins", "top_video_pins" ], "recommended_value": "IMPRESSION", "options_by_data_view": { "top_pins": [ { "value": "ENGAGEMENT", "label": "Engagements" }, { "value": "IMPRESSION", "label": "Impressions" }, { "value": "OUTBOUND_CLICK", "label": "Outbound clicks" }, { "value": "PIN_CLICK", "label": "Pin clicks" }, { "value": "SAVE", "label": "Saves" } ], "top_video_pins": [ { "value": "IMPRESSION", "label": "Impressions" }, { "value": "SAVE", "label": "Saves" }, { "value": "OUTBOUND_CLICK", "label": "Outbound clicks" }, { "value": "VIDEO_MRC_VIEW", "label": "Video MRC views" }, { "value": "VIDEO_AVG_WATCH_TIME", "label": "Video average watch time" }, { "value": "VIDEO_V50_WATCH_TIME", "label": "Video V50 watch time" }, { "value": "QUARTILE_95_PERCENT_VIEW", "label": "Quartile 95% view" }, { "value": "VIDEO_10S_VIEW", "label": "Video 10s view" }, { "value": "VIDEO_START", "label": "Video start" } ] } } ], "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_snapchat_ads": { "summary": "snapchat_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "snapchat_ads", "name": "Snapchat Ads", "category": "paid_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "account", "name": "Account" }, { "id": "demographics_lifetime", "name": "Demographics (lifetime)" }, { "id": "campaign", "name": "Campaign" }, { "id": "ad_group", "name": "Ad group" }, { "id": "ad", "name": "Ad" } ], "settings": [ { "id": "click_window", "name": "Click window", "description": "Click attribution window in days.", "recommended_value": "28_DAY", "options": [ { "value": "1_DAY", "label": "1 day" }, { "value": "7_DAY", "label": "7 days" }, { "value": "28_DAY", "label": "28 days" } ] }, { "id": "view_window", "name": "View window", "description": "View attribution window. NOTE: value 'none' is lowercase by design; all other values use uppercase.", "recommended_value": "1_DAY", "options": [ { "value": "none", "label": "None" }, { "value": "1_HOUR", "label": "1 hour" }, { "value": "3_HOUR", "label": "3 hours" }, { "value": "6_HOUR", "label": "6 hours" }, { "value": "1_DAY", "label": "1 day" }, { "value": "7_DAY", "label": "7 days" } ] }, { "id": "conversion_report_time", "name": "Show conversion metrics by", "description": "Whether conversions are reported by impression time or conversion time.", "recommended_value": "TIME_OF_IMPRESSION", "options": [ { "value": "TIME_OF_IMPRESSION", "label": "Impression time" }, { "value": "TIME_OF_CONVERSION", "label": "Conversion time" } ] } ], "filters": { "supported": true, "combination": "or", "note": "All filter fields are dimensions; type_of_field='dimension' is REQUIRED in each filter (metric filters are not supported). Snapchat Marketing API only supports OR combination between filter conditions: combination='OR' (default if absent) is accepted; combination='AND' is rejected upfront. For multi-value filters (IN/NOT_IN) provide a comma-separated string in `value` (e.g. 'ACTIVE,PAUSED'). enum fields with `allowed_values` MUST receive one of the listed values; invalid values are rejected upfront. Filter applicability is resolved per inferred level: campaign filters apply to campaign|ad_group|ad; ad_group filters apply to ad_group|ad; ad filters apply to ad. The API returns an explicit error if an inapplicable filter is submitted.", "fields": [ { "id": "campaign_id", "name": "Campaign ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "ad_squad_id", "name": "Ad group ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "ad_id", "name": "Ad ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "campaign_name", "name": "Campaign name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "ad_squad_name", "name": "Ad group name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "ad_name", "name": "Ad name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "campaign_status", "name": "Campaign status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "PAUSED" ], "type_of_field": "dimension" }, { "id": "campaign_buy_model", "name": "Campaign buy model", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "AUCTION", "RESERVED" ], "type_of_field": "dimension" }, { "id": "campaign_objective", "name": "Campaign objective", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "BRAND_AWARENESS", "APP_CONVERSION", "APP_INSTALL", "CATALOG_SALES", "ENGAGEMENT", "LEAD_GENERATION", "VIDEO_VIEW", "WEB_CONVERSION", "PROMOTE_STORIES", "PROMOTE_PLACES" ], "type_of_field": "dimension" }, { "id": "ad_squad_status", "name": "Ad group status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "PAUSED" ], "type_of_field": "dimension" }, { "id": "ad_squad_type", "name": "Ad group type", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "SNAP_ADS", "LENS", "FILTER" ], "type_of_field": "dimension" }, { "id": "ad_squad_billing_event", "name": "Ad group billing event", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "IMPRESSION" ], "type_of_field": "dimension" }, { "id": "ad_squad_bid_strategy", "name": "Ad group bid strategy", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "AUTO_BID", "LOWEST_COST_WITH_MAX_BID", "MIN_ROAS", "TARGET_COST" ], "type_of_field": "dimension" }, { "id": "ad_squad_optimization_goal", "name": "Ad group optimization goal", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "IMPRESSIONS", "SWIPES", "APP_INSTALLS", "VIDEO_VIEWS", "VIDEO_VIEWS_15_SEC", "USES", "STORY_OPENS", "PIXEL_PAGE_VIEW", "PIXEL_ADD_TO_CART", "LANDING_PAGE_VIEW", "PIXEL_PURCHASE", "PIXEL_SIGNUP", "APP_ADD_TO_CART", "APP_PURCHASE", "APP_SIGNUP" ], "type_of_field": "dimension" }, { "id": "ad_squad_delivery_constraint", "name": "Ad group delivery constraint", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "DAILY_BUDGET", "LIFETIME_BUDGET", "REACH_AND_FREQUENCY" ], "type_of_field": "dimension" }, { "id": "ad_squad_pacing_type", "name": "Ad group pacing type", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "STANDARD", "ACCELERATED" ], "type_of_field": "dimension" }, { "id": "ad_status", "name": "Ad status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "ACTIVE", "PAUSED" ], "type_of_field": "dimension" }, { "id": "ad_review_status", "name": "Ad review status", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "PENDING", "APPROVED", "REJECTED" ], "type_of_field": "dimension" }, { "id": "ad_type", "name": "Ad type", "category": "enum", "operators": [ "IN", "NOT_IN" ], "allowed_values": [ "SNAP_AD", "APP_INSTALL", "REMOTE_WEBPAGE", "DEEP_LINK", "STORY", "AD_TO_LENS", "AD_TO_CALL", "AD_TO_MESSAGE", "FILTER", "LENS", "LENS_WEB_VIEW", "LENS_APP_INSTALL", "LENS_DEEP_LINK", "COLLECTION", "LEAD_GENERATION" ], "type_of_field": "dimension" } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_twitter_ads": { "summary": "twitter_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "twitter_ads", "name": "Twitter Ads", "category": "paid_social", "supports_custom_fields_per_account": false, "notes": [ "The native Twitter Ads API is asynchronous (the platform queues the query, polls until ready, returns results). For small date ranges this is typically transparent, but large date ranges may exceed the request timeout -- prefer date_range <=28 days.", "Use /v1/query/async when querying twitter_ads with large date ranges (>14 days). Sync /v1/query may approach or exceed the 120s server-side timeout for this integration; async (with /v1/query/status polling) provides predictable behavior." ], "data_views": [ { "id": "account", "name": "Account" }, { "id": "funding_source", "name": "Funding source" }, { "id": "campaign", "name": "Campaign" }, { "id": "ad_group", "name": "Ad group" }, { "id": "promoted_tweet", "name": "Promoted tweet" } ], "settings": [ { "id": "placement", "name": "Placement", "description": "Which inventory to query. ALL_ON_TWITTER includes Twitter app and twitter.com; PUBLISHER_NETWORK is the Twitter Audience Platform (off-Twitter inventory).", "recommended_value": "ALL_ON_TWITTER", "options": [ { "value": "ALL_ON_TWITTER", "label": "All on Twitter" }, { "value": "PUBLISHER_NETWORK", "label": "Publisher Network" } ] } ], "filters": { "supported": true, "combination": "and", "note": "All filter fields are dimensions; type_of_field='dimension' is REQUIRED. Twitter Ads API only supports AND combination between filter conditions: combination='AND' (default if absent) is accepted; combination='OR' is rejected upfront with a clear error. For multi-value filters split conditions across multiple entries in filters[]. Filter applicability is resolved per inferred level: campaignId applies to data_view=campaign|ad_group|promoted_tweet; lineItemId applies to data_view=ad_group|promoted_tweet; promotedTweetId applies to data_view=promoted_tweet. Segmentation types (AGE, GENDER, INTERESTS, KEYWORDS, etc.) appear as OUTPUT dimensions in /v1/fields but are NOT filterable.", "fields": [ { "id": "campaignId", "name": "Campaign ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "lineItemId", "name": "Ad group ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "promotedTweetId", "name": "Promoted tweet ID", "category": "id", "operators": [ "EQUALS", "NOT_EQUALS" ], "type_of_field": "dimension" }, { "id": "fundingInstrumentName", "name": "Funding source name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "campaignName", "name": "Campaign name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" }, { "id": "lineItemName", "name": "Ad group name", "category": "name", "operators": [ "CONTAINS", "NOT_CONTAINS" ], "type_of_field": "dimension" } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_mailchimp": { "summary": "mailchimp detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "mailchimp", "name": "Mailchimp", "category": "email", "supports_custom_fields_per_account": false, "notes": [ "Field ids are exposed without the internal email_ prefix (clients use campaignName, emailsSent, opens, listName, ...). Percentage metrics are returned RAW 0-100 (no /100 scaling). Date dimensions are returned in ISO format (yyyy-MM-dd)." ], "data_views": [ { "id": "campaign_overview", "name": "Campaign overview", "type": "campaign" }, { "id": "campaign_24hour_performance", "name": "Campaign - 24-hour performance", "type": "campaign" }, { "id": "campaign_clicks", "name": "Campaign - Click details", "type": "campaign" }, { "id": "campaign_locations", "name": "Campaign - Locations", "type": "campaign" }, { "id": "campaign_domains", "name": "Campaign - Top performing domains", "type": "campaign" }, { "id": "list_overview", "name": "List overview", "type": "list" }, { "id": "list_activity", "name": "List activity", "type": "list" } ], "settings": [ { "id": "entity", "name": "Entity", "description": "REQUIRED. Selects whether /v1/connections lists Mailchimp campaigns or audience lists, and which group of data_views is queryable. campaign_* data_views are valid only when entity=campaign; list_* data_views are valid only when entity=list.", "required": true, "options": [ { "value": "campaign", "label": "Campaign" }, { "value": "list", "label": "List" } ] } ], "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-18T10:30:00Z" } } }, "ok_cross_platform": { "summary": "cross_platform detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "cross_platform", "name": "Cross-platform", "category": "advertising_aggregated", "supports_custom_fields_per_account": false, "notes": [ "cross_platform is a meta-integration: each connection corresponds to a Cross-Platform Accounts Group pre-configured in Reporting Ninja that bundles up to 9 advertising sources (Google Ads, Microsoft Ads, Facebook Ads, Twitter Ads, LinkedIn Ads, Pinterest Ads, TikTok Ads, Snapchat Ads, Reddit Ads). Amazon Ads is excluded by Amazon Ads API terms of service. All per-source configuration (attribution windows, placements, etc.) lives in the AccountsGroup and is NOT exposed in the API request.", "The catalog of fields is fixed: 10 metrics (impressions, clicks, ctr, avgCPC, cost, conversions, costConv, convRate, totalConvValue, ROAS) and 4 dimensions (account, date, week, month). Field ids are exposed without internal prefixes (e.g. impressions, cost). data_view is not required: the response shape is KPI vs TREND depending on whether a time dimension is present in fields[]. account_id MUST equal connection_key (both are the AccountsGroup key)." ], "data_views": null, "settings": null, "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-18T10:30:00Z" } } }, "ok_hubspot": { "summary": "hubspot detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "hubspot", "name": "HubSpot", "category": "crm", "supports_custom_fields_per_account": true, "notes": [ "Field ids are exposed without the internal hs_ prefix. Custom fields for contacts and deals are opt-in via include_custom_fields=true with connection_key + account_id in /v1/fields. /v1/connections returns per-connection metadata blocks (analytics_views[], pipelines_stages[], owners[]) to populate the dynamic setting dropdowns." ], "data_views": [ { "id": "analytics_sources", "name": "Sources - Traffic analytics" }, { "id": "analytics_countries", "name": "Countries - Traffic analytics" }, { "id": "analytics_devices", "name": "Device types - Traffic analytics" }, { "id": "analytics_utm_campaigns", "name": "UTM Campaign - Traffic analytics" }, { "id": "analytics_utm_sources", "name": "UTM Source - Traffic analytics" }, { "id": "analytics_utm_mediums", "name": "UTM Mediums - Traffic analytics" }, { "id": "analytics_utm_contents", "name": "UTM Contents - Traffic analytics" }, { "id": "analytics_utm_terms", "name": "UTM Terms - Traffic analytics" }, { "id": "all_pages", "name": "All page types - Traffic analytics" }, { "id": "landing_pages", "name": "Landing pages - Traffic analytics" }, { "id": "website_pages", "name": "Website pages - Traffic analytics" }, { "id": "blog_posts", "name": "Blog posts - Traffic analytics" }, { "id": "knowledge_articles", "name": "Knowledge articles - Traffic analytics" }, { "id": "forms", "name": "Forms" }, { "id": "marketing_emails", "name": "Emails - Marketing" }, { "id": "marketing_campaigns", "name": "Campaigns - Marketing" }, { "id": "marketing_device_type", "name": "Device types - Marketing" }, { "id": "lifecycle_stages", "name": "Lifecycle stages" }, { "id": "contacts", "name": "Contacts" }, { "id": "deals", "name": "Deals" } ], "settings": [ { "id": "analytics_view", "name": "Analytics view", "applies_to_data_views": [ "analytics_sources", "analytics_countries", "analytics_devices", "analytics_utm_campaigns", "analytics_utm_sources", "analytics_utm_mediums", "analytics_utm_contents", "analytics_utm_terms", "all_pages", "landing_pages", "website_pages", "blog_posts", "knowledge_articles" ], "dynamic": true, "recommended_value": "HUBSPOT_ALL_ANALYTICS_ACTIVITIES" }, { "id": "analytics_sources", "name": "Sources", "applies_to_data_views": [ "analytics_sources" ], "multi_select": true, "options": [ { "value": "direct", "label": "Direct traffic" }, { "value": "organic", "label": "Organic search" }, { "value": "paid", "label": "Paid search" }, { "value": "email", "label": "Email marketing" }, { "value": "referrals", "label": "Referrals" }, { "value": "social", "label": "Social media" }, { "value": "other", "label": "Other campaigns" }, { "value": "offline", "label": "Offline sources" } ], "recommended_value": [ "direct", "organic", "paid", "email", "referrals", "social", "other", "offline" ] }, { "id": "queried_date", "name": "Queried date", "applies_to_data_views": [ "contacts" ], "recommended_value": "hs_createdate", "options": [ { "value": "hs_createdate", "label": "Create date" }, { "value": "hs_hs_lifecyclestage_subscriber_date", "label": "Became a subscriber date" }, { "value": "hs_hs_lifecyclestage_lead_date", "label": "Became a lead date" }, { "value": "hs_hs_lifecyclestage_marketingqualifiedlead_date", "label": "Became a marketing qualified lead date" }, { "value": "hs_hs_lifecyclestage_salesqualifiedlead_date", "label": "Became a sales qualified lead date" }, { "value": "hs_hs_lifecyclestage_opportunity_date", "label": "Became an opportunity date" }, { "value": "hs_hs_lifecyclestage_customer_date", "label": "Became a customer date" }, { "value": "hs_hs_lifecyclestage_evangelist_date", "label": "Became an evangelist date" }, { "value": "hs_hs_lifecyclestage_other_date", "label": "Became an other lifecycle date" } ] }, { "id": "queried_date", "name": "Queried date", "applies_to_data_views": [ "deals" ], "recommended_value": "hs_createdate", "options": [ { "value": "hs_createdate", "label": "Create date" }, { "value": "hs_closedate", "label": "Close date" }, { "value": "hs_notes_last_updated", "label": "Last activity date" } ] }, { "id": "lifecycle_stage", "name": "Lifecycle stage", "applies_to_data_views": [ "contacts" ], "recommended_value": "HUBSPOT_ANY_CONTACT_STAGE", "options": [ { "value": "HUBSPOT_ANY_CONTACT_STAGE", "label": "Any" }, { "value": "subscriber", "label": "Subscriber" }, { "value": "lead", "label": "Lead" }, { "value": "marketingqualifiedlead", "label": "Marketing qualified lead" }, { "value": "salesqualifiedlead", "label": "Sales qualified lead" }, { "value": "opportunity", "label": "Opportunity" }, { "value": "customer", "label": "Customer" }, { "value": "evangelist", "label": "Evangelist" }, { "value": "other", "label": "Other lifecycle" } ] }, { "id": "pipeline_stage", "name": "Pipeline and stage", "applies_to_data_views": [ "deals" ], "dynamic": true, "note": "Values returned in /v1/connections (pipelines_stages[] block). Format `pipelineId###stageId`.", "recommended_value": "HUBSPOT_ANY_DEAL_PIPELINE###HUBSPOT_ANY_DEAL_STAGE" }, { "id": "owner", "name": "Owner", "applies_to_data_views": [ "contacts", "deals" ], "dynamic": true, "note": "Values returned in /v1/connections (owners[] block per connection).", "recommended_value": "HUBSPOT_ANY_OWNER" } ], "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-18T10:30:00Z" } } }, "ok_twitter_analytics": { "summary": "twitter_analytics detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "twitter_analytics", "name": "Twitter Analytics", "category": "organic_social", "supports_custom_fields_per_account": false, "notes": [ "Twitter Analytics exposes a single profile-lifetime scope (followers, following, tweets, listed counts and derived ratios). Tweets, mentions and search analytics scopes were disabled by the Twitter API v2 migration in April 2023 and are not available through this REST API. fields[] requires at least one metric; the pseudo-dimension twanalytics_account is the only dimension available (optional); no time dimensions, no breakdowns." ], "data_views": null, "settings": null, "filters": { "supported": false } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } }, "ok_reddit_ads": { "summary": "reddit_ads detail", "value": { "status": "ok", "data": { "integrations": [{ "id": "reddit_ads", "name": "Reddit Ads", "category": "paid_social", "supports_custom_fields_per_account": false, "data_views": [ { "id": "account", "name": "Account" }, { "id": "campaign", "name": "Campaign" }, { "id": "ad_group", "name": "Ad group" }, { "id": "ad", "name": "Ad" } ], "settings": null, "filters": { "supported": true, "combination": "or", "note": "Reddit Marketing API accepts only POSITIVE operators: EQUALS for id fields, CONTAINS for name fields, IN for enum fields. Negative variants (NOT_EQUALS, NOT_CONTAINS, NOT_IN) are NOT supported and are rejected upfront with a clear error. All filter fields are dimensions; type_of_field='dimension' is REQUIRED in each filter (metric filters are not supported). Combination must be 'OR'; AND is rejected upfront. For multi-value filters (IN) provide a comma-separated string in `value` (e.g. 'ACTIVE,PAUSED'). The 3 enum fields (campaign_effective_status, ad_group_effective_status, ad_effective_status) share the same 11-value list. Filter applicability is resolved per inferred level: campaign filters apply to campaign|ad_group|ad; ad_group filters apply to ad_group|ad; ad filters apply to ad. The API returns an explicit error if an inapplicable filter is submitted.", "fields": [ { "id": "campaign_id", "name": "Campaign ID", "category": "id", "operators": [ "EQUALS" ], "type_of_field": "dimension" }, { "id": "ad_group_id", "name": "Ad group ID", "category": "id", "operators": [ "EQUALS" ], "type_of_field": "dimension" }, { "id": "ad_id", "name": "Ad ID", "category": "id", "operators": [ "EQUALS" ], "type_of_field": "dimension" }, { "id": "campaign_name", "name": "Campaign name", "category": "name", "operators": [ "CONTAINS" ], "type_of_field": "dimension" }, { "id": "ad_group_name", "name": "Ad group name", "category": "name", "operators": [ "CONTAINS" ], "type_of_field": "dimension" }, { "id": "ad_name", "name": "Ad name", "category": "name", "operators": [ "CONTAINS" ], "type_of_field": "dimension" }, { "id": "campaign_effective_status", "name": "Campaign status", "category": "enum", "operators": [ "IN" ], "allowed_values": [ "PENDING_BILLING_INFO", "PENDING_REVIEW", "PENDING_ID_VERIFICATION", "ACTIVE", "REJECTED", "PAUSED", "CAMPAIGN_PAUSED", "AD_GROUP_PAUSED", "COMPLETED", "ARCHIVED", "DELETED" ], "type_of_field": "dimension" }, { "id": "ad_group_effective_status", "name": "Ad group status", "category": "enum", "operators": [ "IN" ], "allowed_values": [ "PENDING_BILLING_INFO", "PENDING_REVIEW", "PENDING_ID_VERIFICATION", "ACTIVE", "REJECTED", "PAUSED", "CAMPAIGN_PAUSED", "AD_GROUP_PAUSED", "COMPLETED", "ARCHIVED", "DELETED" ], "type_of_field": "dimension" }, { "id": "ad_effective_status", "name": "Ad status", "category": "enum", "operators": [ "IN" ], "allowed_values": [ "PENDING_BILLING_INFO", "PENDING_REVIEW", "PENDING_ID_VERIFICATION", "ACTIVE", "REJECTED", "PAUSED", "CAMPAIGN_PAUSED", "AD_GROUP_PAUSED", "COMPLETED", "ARCHIVED", "DELETED" ], "type_of_field": "dimension" } ] } }] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-17T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/connections": { "post": { "operationId": "listConnections", "tags": [ "Connections" ], "summary": "List connections for an integration", "description": "A connection represents an OAuth-authorized link to the underlying platform (e.g. a Meta user with access to multiple Ad Accounts). Each connection groups several account_ids.", "x-mcp-description": "Use this tool to discover which accounts the user can query. Pass the integration_id (from /integrations) and you get back a list of connection_key + accounts, each with account_id and account_name. You'll use the pair (connection_key, account_id) in subsequent calls to /fields and /query.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionsRequest" }, "examples": { "facebook_ads": { "summary": "Facebook Ads (no settings required)", "value": { "integration_id": "facebook_ads" } }, "mailchimp_campaign": { "summary": "Mailchimp (entity=campaign; response includes pseudo-account ALL_CAMPAIGNS_SENT_IN_DATE_RANGE)", "value": { "integration_id": "mailchimp", "settings": { "entity": "campaign" } } }, "mailchimp_list": { "summary": "Mailchimp (entity=list)", "value": { "integration_id": "mailchimp", "settings": { "entity": "list" } } }, "cross_platform": { "summary": "Cross-platform (returns the user's AccountsGroups; each group becomes a connection whose single account has account_id = connection_key)", "value": { "integration_id": "cross_platform" } }, "hubspot": { "summary": "HubSpot (response also includes analytics_views[], pipelines_stages[], owners[] per connection -- used to build the dynamic settings dropdowns)", "value": { "integration_id": "hubspot" } } } } } }, "responses": { "200": { "description": "OK or business error envelope.", "content": { "application/json": { "examples": { "ok": { "value": { "status": "ok", "data": { "connections": [ { "connection_key": "consumer@example.com", "connection_name": "consumer@example.com", "status": "active", "accounts": [ { "account_id": "0000000000000000", "account_name": "My Meta Ads account", "currency": "EUR" } ] } ] }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/fields": { "post": { "operationId": "listFields", "tags": [ "Fields" ], "summary": "List dimensions and metrics for a connection", "description": "Returns the set of field_ids you can pass to /v1/query, plus default_dimension and default_metric suggestions. By default returns only the standard catalog. To include account-specific custom fields (e.g. Facebook Ads custom conversions, GA4 custom metrics and dimensions), set include_custom_fields=true and provide connection_key + account_id. include_custom_fields is only allowed when the integration's catalog declares supports_custom_fields_per_account=true. For all other integrations, sending include_custom_fields (or connection_key/account_id) returns an error.", "x-mcp-description": "Use this tool to discover the available dimensions and metrics for a given account before composing a query. Field IDs returned here are exactly what you should pass in /v1/query.fields (without integration-specific prefixes). The naming convention depends on the integration: facebook_ads uses underscores (e.g. `campaign_name`, `day`, `impressions`, `clicks`, `spend`), google_ads uses dotted paths (e.g. `campaign.name`, `segments.date`, `metrics.impressions`, `metrics.clicks`, `metrics.cost_micros`). The `dim_met` attribute tells you whether a field is a dimension or a metric.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldsRequest" }, "examples": { "facebook_ads_standard": { "summary": "Facebook Ads -- standard catalog only (no custom conversions)", "value": { "integration_id": "facebook_ads" } }, "facebook_ads_with_custom": { "summary": "Facebook Ads -- include account-specific custom conversions", "value": { "integration_id": "facebook_ads", "include_custom_fields": true, "connection_key": "consumer@example.com", "account_id": "0000000000000000" } }, "google_ads": { "summary": "Google Ads (data_view required; no custom fields supported)", "value": { "integration_id": "google_ads", "data_view": "campaign" } }, "ga4_standard": { "summary": "GA4 -- standard catalog only (no custom dimensions/metrics)", "value": { "integration_id": "ga4" } }, "ga4_with_custom": { "summary": "GA4 -- include account-specific custom dimensions and metrics", "value": { "integration_id": "ga4", "include_custom_fields": true, "connection_key": "user@example.com", "account_id": "properties/123456789" } }, "microsoft_ads": { "summary": "Microsoft Ads (data_view required; no custom fields supported)", "value": { "integration_id": "microsoft_ads", "data_view": "campaign_performance" } }, "youtube": { "summary": "YouTube (data_view required; no custom fields supported)", "value": { "integration_id": "youtube", "data_view": "basic" } }, "google_search_console": { "summary": "Google Search Console (no data_view; no custom fields supported)", "value": { "integration_id": "google_search_console" } }, "google_business_profile": { "summary": "Google Business Profile (data_view required; no custom fields supported)", "value": { "integration_id": "google_business_profile", "data_view": "performance" } }, "facebook_insights": { "summary": "Facebook Insights (data_view required; no custom fields supported)", "value": { "integration_id": "facebook_insights", "data_view": "page" } }, "instagram_insights": { "summary": "Instagram Insights (data_view required; no custom fields supported)", "value": { "integration_id": "instagram_insights", "data_view": "account" } }, "linkedin_ads": { "summary": "LinkedIn Ads (data_view required; no custom fields supported)", "value": { "integration_id": "linkedin_ads", "data_view": "campaign" } }, "linkedin_pages": { "summary": "LinkedIn Pages (data_view required; no custom fields supported)", "value": { "integration_id": "linkedin_pages", "data_view": "lifetime_followers" } }, "tiktok_ads": { "summary": "TikTok Ads (data_view required; no custom fields supported)", "value": { "integration_id": "tiktok_ads", "data_view": "campaign" } }, "tiktok_organic": { "summary": "TikTok Organic (data_view required; no custom fields supported)", "value": { "integration_id": "tiktok_organic", "data_view": "profile" } }, "pinterest_ads": { "summary": "Pinterest Ads (data_view required; no custom fields supported)", "value": { "integration_id": "pinterest_ads", "data_view": "campaign" } }, "pinterest_organic": { "summary": "Pinterest Organic (data_view required; no custom fields supported)", "value": { "integration_id": "pinterest_organic", "data_view": "top_pins" } }, "snapchat_ads": { "summary": "Snapchat Ads (data_view required; no custom fields supported)", "value": { "integration_id": "snapchat_ads", "data_view": "campaign" } }, "reddit_ads": { "summary": "Reddit Ads (data_view required; no custom fields supported)", "value": { "integration_id": "reddit_ads", "data_view": "campaign" } }, "twitter_analytics": { "summary": "Twitter Analytics (data_view NOT required -- single hardcoded scope; no custom fields supported)", "value": { "integration_id": "twitter_analytics" } }, "twitter_ads": { "summary": "Twitter Ads (data_view required; no custom fields supported)", "value": { "integration_id": "twitter_ads", "data_view": "campaign" } }, "mailchimp_campaign_overview": { "summary": "Mailchimp (entity=campaign + data_view=campaign_overview; field ids returned WITHOUT internal email_ prefix)", "value": { "integration_id": "mailchimp", "settings": { "entity": "campaign" }, "data_view": "campaign_overview" } }, "mailchimp_list_activity": { "summary": "Mailchimp (entity=list + data_view=list_activity)", "value": { "integration_id": "mailchimp", "settings": { "entity": "list" }, "data_view": "list_activity" } }, "cross_platform": { "summary": "Cross-platform (no data_view; no custom fields; field ids returned WITHOUT internal cx: prefix; fixed catalog of 14 fields)", "value": { "integration_id": "cross_platform" } }, "hubspot_analytics_sources": { "summary": "HubSpot (data_view=analytics_sources; field ids returned WITHOUT internal hs_ prefix)", "value": { "integration_id": "hubspot", "data_view": "analytics_sources" } }, "hubspot_contacts_custom_fields": { "summary": "HubSpot (data_view=contacts with include_custom_fields=true to receive per-account custom contact properties; connection_key + account_id REQUIRED)", "value": { "integration_id": "hubspot", "data_view": "contacts", "include_custom_fields": true, "connection_key": "", "account_id": "" } } } } } }, "responses": { "200": { "description": "OK or business error envelope.", "content": { "application/json": { "examples": { "ok": { "value": { "status": "ok", "data": { "fields": [ { "field_id": "impressions", "field_name": "Impressions", "field_description": "The number of times your ads were on screen", "field_type": "number", "dim_met": "metric" }, { "field_id": "campaign_name", "field_name": "Campaign", "field_description": "", "field_type": "text", "dim_met": "dimension" } ], "default_dimension": "account_name", "default_metric": "impressions" }, "meta": { "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/query": { "post": { "operationId": "executeQuery", "tags": [ "Query" ], "summary": "Run a data query", "description": "Returns up to `limit` rows for the requested fields over the requested date range. Supports filters, settings and period-over-period comparison via compare_to. Pagination is via `cursor`. Cursors are bound to the exact query+account; mutating any input invalidates the cursor and the response is treated as a fresh first page. Numeric values that cannot be computed (for example a ratio with a zero denominator) are returned as null.", "x-mcp-description": "Use this tool to retrieve marketing data. Compose a request with: integration_id, connection_key, account_id, fields (array of field_ids from /v1/fields), date_range (preset or custom), optional filters, optional compare_to for period-over-period analysis, and a limit. Results come back row-by-row; when compare_to is set, each row contains current, previous and change sub-objects. Always pass field_ids and filter field IDs WITHOUT integration-specific prefixes (e.g. 'impressions', NOT 'fb:impressions'). For ga4 specifically: (1) each filter MUST include `type_of_field` (\"dimension\" or \"metric\") and may include `combination` (\"AND\"/\"OR\"); (2) all filters must share the same type_of_field; (3) temporal dimensions (date/week/month) come back in different formats depending on whether the query is trend (single temporal dim) or non-trend (2+ dims): trend returns date='YYYY-MM-DD', month='YYYY-MM', week='YYYY-MM-DD of the Monday of that week'; non-trend returns date='YYYYMMDD', month='MM' (no year), week='WW' (no year); (4) percent metrics are returned in 0-100 scale, not 0-1.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "facebook_ads": { "summary": "Facebook Ads (no data_view)", "value": { "integration_id": "facebook_ads", "connection_key": "consumer@example.com", "account_id": "0000000000000000", "fields": [ "impressions", "clicks", "spend", "campaign_name", "day" ], "date_range": { "preset": "lastmonth" }, "compare_to": { "preset": "previous" }, "comparison_type": "percentage", "settings": { "attribution_window": "ATTRIBUTION_MODEL_VIEW_CLICK###VIEW_ATTRIBUTION_WINDOW_1D###CLICK_ATTRIBUTION_WINDOW_7D" }, "filters": [ { "field": "campaign.name", "operator": "CONTAINS", "value": "brand" } ], "limit": 100 } }, "google_ads": { "summary": "Google Ads (data_view required, dotted field names, multi-value filters supported)", "value": { "integration_id": "google_ads", "connection_key": "user@example.com", "account_id": "1234567890", "data_view": "campaign", "fields": [ "campaign.name", "metrics.clicks", "metrics.impressions", "metrics.cost_micros", "segments.date" ], "date_range": { "preset": "lastxdays", "x": 7 }, "filters": [ { "field": "campaign.status", "operator": "IN", "value": [ "ENABLED", "PAUSED" ] }, { "field": "metrics.cost_micros", "operator": "GREATER_THAN", "value": 100 } ], "limit": 100 } }, "ga4": { "summary": "GA4 (dynamic filter fields, type_of_field required per filter, AND/OR per filter)", "value": { "integration_id": "ga4", "connection_key": "user@example.com", "account_id": "properties/123456789", "fields": [ "country", "sessions", "activeUsers", "date" ], "date_range": { "preset": "lastxdays", "x": 7 }, "filters": [ { "field": "country", "operator": "CONTAINS", "value": "United", "type_of_field": "dimension", "combination": "AND" }, { "field": "country", "operator": "CONTAINS", "value": "Kingdom", "type_of_field": "dimension", "combination": "OR" } ], "limit": 100 } }, "microsoft_ads": { "summary": "Microsoft Ads (data_view required; filter fields scoped to data_view, allowed_values for enums)", "value": { "integration_id": "microsoft_ads", "connection_key": "user@example.com", "account_id": "123456789", "data_view": "campaign_performance", "fields": [ "CampaignName", "Impressions", "Clicks", "Spend", "TimePeriod" ], "date_range": { "preset": "lastxdays", "x": 7 }, "filters": [ { "field": "CampaignStatus", "operator": "IN_LIST", "value": [ "Active", "Paused" ] }, { "field": "CampaignName", "operator": "CONTAINS", "value": "Brand" } ], "limit": 100 } }, "youtube": { "summary": "YouTube (data_view required; only IN_LIST operator; single-value-only for most fields)", "value": { "integration_id": "youtube", "connection_key": "user@example.com", "account_id": "UCxxxxxxxxxxxxxxxxxxxxxxx", "data_view": "traffic_sources", "fields": [ "day", "insightTrafficSourceType", "views", "estimatedMinutesWatched" ], "date_range": { "preset": "lastxdays", "x": 28 }, "filters": [ { "field": "country", "operator": "IN_LIST", "value": [ "ES" ] }, { "field": "subscribedStatus", "operator": "IN_LIST", "value": [ "SUBSCRIBED" ] }, { "field": "insightTrafficSourceType", "operator": "IN_LIST", "value": [ "YT_SEARCH" ] } ], "limit": 100 } }, "google_search_console": { "summary": "Google Search Console (no data_view; account_id is the site URL; setting search_type; single-value filters; max 1 dimension and >=1 metric in fields[])", "value": { "integration_id": "google_search_console", "connection_key": "user@example.com", "account_id": "https://example.com/", "fields": [ "query", "clicks", "impressions", "ctr", "avgposition" ], "date_range": { "preset": "lastxdays", "x": 28 }, "filters": [ { "field": "country", "operator": "EQUALS", "value": "usa" }, { "field": "device", "operator": "EQUALS", "value": "DESKTOP" } ], "settings": { "search_type": "web" }, "limit": 100 } }, "google_business_profile": { "summary": "Google Business Profile (data_view required; account_id is the full 'accounts/X/locations/Y' path; filters NOT supported; at least 1 metric required; max 1 dimension for performance)", "value": { "integration_id": "google_business_profile", "connection_key": "user@example.com", "account_id": "accounts/12345/locations/67890", "data_view": "performance", "fields": [ "day", "business_impressions_total_calc", "website_clicks", "business_direction_requests" ], "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 100 } }, "facebook_insights": { "summary": "Facebook Insights (data_view required; account_id is the plain page_id; filters NOT supported; post/reel require dim+metric; aggregated data_views accept only metrics)", "value": { "integration_id": "facebook_insights", "connection_key": "user@example.com", "account_id": "123456789012345", "data_view": "page", "fields": [ "day", "page_media_view" ], "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 28 } }, "instagram_insights": { "summary": "Instagram Insights (data_view required; account_id is the plain ig_user_id; filters NOT supported; posts require dim+metric; posts_aggregated accepts only metrics", "value": { "integration_id": "instagram_insights", "connection_key": "user@example.com", "account_id": "17841407839256743", "data_view": "account", "fields": [ "followers_count_metadata" ], "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 1 } }, "linkedin_ads": { "summary": "LinkedIn Ads (data_view required; account_id is the plain ad account numeric id; filters supported with combination='or' only -- AND is rejected; type_of_field='dimension' is REQUIRED in each filter; enum fields validate value against allowed_values; multi-value filters use comma-separated string)", "value": { "integration_id": "linkedin_ads", "connection_key": "user@example.com", "account_id": "123456789", "data_view": "campaign", "fields": [ "campaignId", "impressions", "clicks" ], "date_range": { "preset": "lastxdays", "x": 28 }, "filters": [ { "field": "campaignStatus", "operator": "IN", "value": "ACTIVE,PAUSED", "type_of_field": "dimension", "combination": "OR" } ], "limit": 100 } }, "linkedin_pages": { "summary": "LinkedIn Pages (data_view required; account_id is the EXACT URN urn:li:organization:N from /v1/connections; filters NOT supported; lifetime_followers requires exactly 1 dim + 1 metric; specific_shares post-level mode requires the mandatory postText dimension; date_range is required by the generic /v1/query validation even for lifetime/realtime data_views where it is silently ignored by the executor)", "value": { "integration_id": "linkedin_pages", "connection_key": "user@example.com", "account_id": "urn:li:organization:2414183", "data_view": "lifetime_followers", "fields": [ "region", "organicFollowerCount" ], "date_range": { "preset": "lastxdays", "x": 30 }, "limit": 50 } }, "tiktok_ads": { "summary": "TikTok Ads (data_view required; account_id is the plain advertiser_id; filters supported with combination='or' only -- AND is rejected; type_of_field='dimension' is REQUIRED in each filter; 10 enum fields validate value against allowed_values; multi-value filters use comma-separated string)", "value": { "integration_id": "tiktok_ads", "connection_key": "user@example.com", "account_id": "6977519744471597058", "data_view": "campaign", "fields": [ "campaign_id", "impressions", "clicks" ], "date_range": { "preset": "lastxdays", "x": 28 }, "filters": [ { "field": "campaign_operation_status", "operator": "IN", "value": "ENABLE", "type_of_field": "dimension", "combination": "OR" } ], "limit": 100 } }, "tiktok_organic": { "summary": "TikTok Organic (data_view required; account_id is the plain TikTok Business id from /v1/connections; filters NOT supported; audience requires exactly 1 dim + 1 metric; video requires at least 1 dim + 1 metric)", "value": { "integration_id": "tiktok_organic", "connection_key": "user@example.com", "account_id": "", "data_view": "profile", "fields": [ "day", "profile_video_views" ], "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 28 } }, "pinterest_ads": { "summary": "Pinterest Ads (data_view required; account_id is the plain Pinterest ad_account_id; 4 settings strictly validated -- defaults injected if absent; filters supported with combination='or' only -- AND is rejected; type_of_field='dimension' is REQUIRED in each filter; 8 enum fields validate value against allowed_values; multi-value filters use comma-separated string; cross-setting combinations may be rejected by Pinterest with a clear executor message)", "value": { "integration_id": "pinterest_ads", "connection_key": "user@example.com", "account_id": "", "data_view": "campaign", "fields": [ "CAMPAIGN_NAME", "IMPRESSION_1", "CLICKTHROUGH_1", "SPEND_IN_DOLLAR" ], "filters": [ { "field": "CAMPAIGN_STATUS", "operator": "IN", "value": "ACTIVE,PAUSED", "type_of_field": "dimension", "combination": "OR" } ], "settings": { "click_window": "30", "engagement_window": "30", "view_window": "1", "conversion_report_time": "TIME_OF_AD_ACTION" }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 28 } }, "pinterest_organic": { "summary": "Pinterest Organic (data_view required; account_id is the Pinterest user account id from /v1/connections; filters NOT supported; 3 declarative settings strictly validated -- pinterest_sort_by uses options_by_data_view with 5 values for top_pins and 9 video-specific values for top_video_pins; settings outside applies_to_data_views are silently ignored)", "value": { "integration_id": "pinterest_organic", "connection_key": "user@example.com", "account_id": "", "data_view": "top_pins", "fields": [ "TITLE", "IMPRESSION", "OUTBOUND_CLICK", "SAVE" ], "settings": { "pinterest_source": "YOUR_PINS", "pinterest_claimed_content": "BOTH", "pinterest_sort_by": "ENGAGEMENT" }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 28 } }, "snapchat_ads": { "summary": "Snapchat Ads (data_view required; account_id is the Snapchat ad_account_id UUID; 3 settings strictly validated -- defaults injected ALWAYS; filters supported with combination='or' only -- AND rejected; type_of_field='dimension' REQUIRED; 13 enum fields validate value against allowed_values; multi-value filters use comma-separated string; view_window 'none' is lowercase by design)", "value": { "integration_id": "snapchat_ads", "connection_key": "user@example.com", "account_id": "", "data_view": "campaign", "fields": [ "campaign_name", "impressions", "spend", "swipes" ], "filters": [ { "field": "campaign_status", "operator": "IN", "value": "ACTIVE", "type_of_field": "dimension", "combination": "OR" } ], "settings": { "click_window": "28_DAY", "view_window": "1_DAY", "conversion_report_time": "TIME_OF_IMPRESSION" }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 28 } }, "reddit_ads": { "summary": "Reddit Ads (data_view required; account_id is the Reddit ad_account_id from /v1/connections; settings=null; filters supported ONLY with POSITIVE operators -- EQUALS for ids, CONTAINS for names, IN for enums; NOT_EQUALS/NOT_CONTAINS/NOT_IN rejected; combination='or' only -- AND rejected; type_of_field='dimension' REQUIRED; allowed_values shared 11-value list across the 3 effective_status enums)", "value": { "integration_id": "reddit_ads", "connection_key": "user@example.com", "account_id": "", "data_view": "campaign", "fields": [ "campaign_name", "impressions", "spend" ], "filters": [ { "field": "campaign_effective_status", "operator": "IN", "value": "ACTIVE", "type_of_field": "dimension", "combination": "OR" } ], "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 28 } }, "twitter_analytics": { "summary": "Twitter Analytics (data_view NOT required; connection_key='@username'; account_id is the Twitter user_id; single profile-lifetime scope; fields[] requires >=1 metric; pseudo-dimension `account` optional)", "value": { "integration_id": "twitter_analytics", "connection_key": "@reportingninja", "account_id": "", "fields": [ "followers", "tweets", "following" ], "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 28 } }, "twitter_ads": { "summary": "Twitter Ads (data_view required; account_id is the Twitter Ads alphanumeric id from /v1/connections; settings.placement REQUIRED -- ALL_ON_TWITTER default; filters supported with combination='and' only -- OR rejected; type_of_field='dimension' REQUIRED; no enums; native API async via job-queue but exposed as sync -- prefer date_range <=28d)", "value": { "integration_id": "twitter_ads", "connection_key": "user@example.com", "account_id": "", "data_view": "campaign", "fields": [ "campaignName", "impressions", "billedChargeLocalMicro" ], "filters": [ { "field": "campaignName", "operator": "CONTAINS", "value": "summer", "type_of_field": "dimension", "combination": "AND" } ], "settings": { "placement": "ALL_ON_TWITTER" }, "date_range": { "preset": "lastxdays", "x": 7 }, "limit": 28 } }, "mailchimp_campaign_overview": { "summary": "Mailchimp (entity=campaign + data_view=campaign_overview; settings.entity REQUIRED no default; filters NOT supported; field ids WITHOUT email_ prefix; ALL_CAMPAIGNS_SENT_IN_DATE_RANGE valid account_id only with data_view=campaign_overview; dates ISO yyyy-MM-dd; percentages raw 0-100)", "value": { "integration_id": "mailchimp", "connection_key": "user@example.com", "account_id": "", "data_view": "campaign_overview", "fields": [ "campaignName", "emailsSent", "opens", "clicks" ], "settings": { "entity": "campaign" }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 100 } }, "mailchimp_list_overview": { "summary": "Mailchimp (entity=list + data_view=list_overview)", "value": { "integration_id": "mailchimp", "connection_key": "user@example.com", "account_id": "", "data_view": "list_overview", "fields": [ "listName", "memberCount" ], "settings": { "entity": "list" }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 100 } }, "cross_platform": { "summary": "Cross-platform (no data_view; no settings; no filters; account_id MUST equal connection_key; field ids WITHOUT cx: prefix; fixed catalog of 14 fields)", "value": { "integration_id": "cross_platform", "connection_key": "", "account_id": "", "fields": [ "account", "impressions", "clicks", "cost", "ROAS" ], "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 100 } }, "hubspot_analytics_sources": { "summary": "HubSpot analytics_sources with multi-select sources setting (API renames array to comma-separated `sources` internally)", "value": { "integration_id": "hubspot", "connection_key": "", "account_id": "", "data_view": "analytics_sources", "fields": [ "sessions", "newVisitorSessions", "bounceRate" ], "settings": { "analytics_view": "", "analytics_sources": [ "direct", "organic" ] }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 100 } }, "hubspot_contacts": { "summary": "HubSpot contacts with lifecycle_stage + queried_date + owner settings (note: queried_date for contacts has different options than for deals; sending a setting outside its applies_to_data_views is silently ignored)", "value": { "integration_id": "hubspot", "connection_key": "", "account_id": "", "data_view": "contacts", "fields": [ "contactsCount", "newContactsCount" ], "settings": { "queried_date": "hs_createdate", "lifecycle_stage": "lead", "owner": "" }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 100 } }, "hubspot_deals": { "summary": "HubSpot deals with pipeline_stage + queried_date settings (pipeline_stage format: `pipelineId###stageId`)", "value": { "integration_id": "hubspot", "connection_key": "", "account_id": "", "data_view": "deals", "fields": [ "dealCount", "dealAmount" ], "settings": { "queried_date": "hs_closedate", "pipeline_stage": "###", "owner": "" }, "date_range": { "preset": "lastxdays", "x": 28 }, "limit": 100 } } } } } }, "responses": { "200": { "description": "OK or business error envelope.", "content": { "application/json": { "examples": { "ok_no_compare": { "summary": "Without comparison", "value": { "status": "ok", "data": { "rows": [ { "day": "2026-04-30", "campaign_name": "Brand ES", "impressions": 12340, "clicks": 890, "spend": 234.5 } ] }, "meta": { "total_rows": 847, "returned_rows": 100, "has_more": true, "next_cursor": "eyJoIjoiYWJjIiwiYSI6IjEyMyIsIm8iOjEwMH0=", "date_range_resolved": { "start": "2026-04-01", "end": "2026-04-30" }, "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } }, "ok_with_compare": { "summary": "With period-over-period comparison", "value": { "status": "ok", "data": { "rows": [ { "campaign_name": "Brand ES", "current": { "impressions": 12340, "clicks": 890, "spend": 234.5 }, "previous": { "impressions": 10200, "clicks": 720, "spend": 210.0 }, "change": { "impressions": { "absolute": 2140, "percentage": 20.98 }, "clicks": { "absolute": 170, "percentage": 23.61 }, "spend": { "absolute": 24.5, "percentage": 11.67 } } } ] }, "meta": { "date_range_resolved": { "start": "2026-04-01", "end": "2026-04-30" }, "compare_date_range_resolved": { "start": "2026-03-01", "end": "2026-03-31" }, "comparison_type": "percentage", "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/query/async": { "post": { "summary": "Submit an async query", "description": "Validates the input identically to /v1/query. On success persists the query as a background job and returns a job_id immediately. The query is processed asynchronously; poll /v1/query/status to retrieve the result. Successful results are retained for 8 hours after completion. Authorization: Bearer token (same as other endpoints).", "operationId": "submitAsyncQuery", "tags": [ "Query" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } }, "responses": { "200": { "description": "Job accepted and persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncQueryAcceptedResponse" }, "example": { "status": "ok", "data": { "job_id": "1234567890", "status": "pending" }, "meta": { "request_id": "req_xxxxxxxxxxxx", "timestamp": "2026-05-25T10:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/query/status": { "post": { "summary": "Poll an async query's status", "description": "Returns the current state of a previously submitted async query (pending, running, success, error). When status is `success`, the original /v1/query response body is embedded under data.result with the same shape (status + data.rows[] + meta). When status is `error`, data.error_message contains the failure reason. Authorization: same Bearer token. A job_id belonging to another account returns the same `job_id not found or expired` envelope as unknown ids. Successful results are retained for 8 hours; after that the job returns the same not-found envelope.", "operationId": "queryStatus", "tags": [ "Query" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id" ], "properties": { "job_id": { "type": "string", "example": "1234567890" } } } } } }, "responses": { "200": { "description": "Current status of the job (or business error envelope when not found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncQueryStatusResponse" }, "example": { "status": "ok", "data": { "job_id": "1234567890", "status": "success", "created_at": 1716639000000, "started_at": 1716639020000, "completed_at": 1716639060000, "result": { "status": "ok", "data": { "rows": [ { "day": "2026-04-30", "impressions": 12340 } ] }, "meta": { "request_id": "req_xxxxxxxxxxxx", "timestamp": "2026-05-25T10:30:00Z", "total_rows": 1, "returned_rows": 1, "has_more": false } } }, "meta": { "request_id": "req_yyyyyyyyyyyy", "timestamp": "2026-05-25T10:31:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your Reporting Ninja public API key, obtained from the REST API tab in the app." } }, "responses": { "RateLimitExceeded": { "description": "Rate limit exceeded. The Retry-After header indicates seconds until the more-restrictive window (per-minute or per-day) resets. Standard error envelope in body.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the more-restrictive window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer", "format": "int64" } }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "schema": { "type": "integer", "format": "int64" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "error_code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry after 42 seconds.", "meta": { "request_id": "req_abc123", "timestamp": "2026-05-26T10:30:00Z" } } } } }, "Unauthorized": { "description": "Invalid or missing Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "status": "error", "error_code": "AUTH_INVALID", "message": "Invalid API key", "meta": { "request_id": "req_abc123", "timestamp": "2026-05-16T10:30:00Z" } } } } }, "InternalError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "EmptyBody": { "type": "object", "description": "No parameters." }, "Meta": { "type": "object", "required": [ "request_id", "timestamp" ], "properties": { "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "OkEnvelope": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "const": "ok" }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ErrorEnvelope": { "type": "object", "required": [ "status", "error_code", "message", "meta" ], "properties": { "status": { "type": "string", "const": "error" }, "error_code": { "type": "string", "description": "Machine-readable code that classifies the error category. Stable across versions. Clients should switch on this code for error handling instead of parsing the `message` text. The HTTP status code alone is NOT sufficient to discriminate validation errors (most return HTTP 200 with status=error) from auth (401) or rate limit (429) -- always read `error_code`.", "enum": [ "AUTH_INVALID", "AUTH_EXPIRED", "RATE_LIMITED", "ENDPOINT_NOT_FOUND", "INVALID_REQUEST", "INVALID_MODE", "MISSING_REQUIRED_FIELD", "INVALID_VALUE", "INVALID_LIMIT", "UNKNOWN_PARAM", "INTEGRATION_NOT_SUPPORTED", "INTEGRATION_NOT_IMPLEMENTED", "FIELD_NOT_AVAILABLE", "FILTER_NOT_WIRED", "INVALID_FILTER", "INVALID_DATE_RANGE", "CONNECTION_NOT_FOUND", "ACCOUNT_NOT_FOUND", "PLAN_LIMIT_REACHED", "PROVIDER_PERMISSION", "JOB_NOT_FOUND", "CURSOR_EXPIRED", "INVALID_CURSOR", "INTERNAL" ] }, "message": { "type": "string", "description": "Human-readable error description. Useful for logs and UIs; not stable across versions -- use `error_code` for programmatic handling." }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "IntegrationDetailRequest": { "type": "object", "required": [ "integration_id" ], "properties": { "integration_id": { "type": "string", "description": "Public integration id (e.g. facebook_ads)." } } }, "Integration": { "type": "object", "required": [ "id", "name", "category", "supports_custom_fields_per_account" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "supports_custom_fields_per_account": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Integration-wide advisories that do not fit in filters/settings/data_views (e.g. data freshness windows, upstream API quotas, billing notes). Optional: only present when there are global notes to publish. Each entry is a short, audience-API sentence; the array is unordered and clients should treat it as a bag of standalone notes." }, "data_views": { "oneOf": [ { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/DataView" } } ] }, "settings": { "oneOf": [ { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/Setting" } } ] }, "filters": { "$ref": "#/components/schemas/FiltersDescriptor" } } }, "DataView": { "type": "object", "required": [ "id", "name" ], "description": "A data view exposed by an integration. The full list of valid `id` values for a given integration is in the response of /v1/integrations/detail (data_views[]). Example for google_ads: 19 views including `customer`, `campaign`, `ad_group`, `keyword_view`, `search_term_view`, etc.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "description": "Public-facing summary explaining what this data_view returns. Short (1-2 sentence) hint for the API consumer about the underlying scope/endpoint and notable restrictions; does NOT replace the integration-level `filters.note` which covers global concerns (settings, prefix, custom fields, etc.). Always present in real responses (iter 24+); omitted from compact examples in this spec for readability but emitted by /v1/integrations/detail for every data_view." }, "type": { "type": "string", "enum": [ "campaign", "list" ], "description": "Mailchimp-only: indicates which entity (campaign|list) this data_view affines with. The API validates that data_view.type matches settings.entity for mailchimp queries. Not present for other integrations." } } }, "Setting": { "type": "object", "description": "Per-request settings that customize the query semantics for a given integration. Behaviour: when a setting's `applies_to_data_views` includes the current data_view (or applies_to_data_views is absent meaning 'always applies'), the setting is REQUIRED in /v1/query and the API rejects with 400 if it is missing. The API validates strictly that the value matches one of the declared `options[]` (or `options_by_data_view[]` when present). Sending a setting with a `data_view` outside its `applies_to_data_views` returns 400. Sending an unknown setting key returns 400. Dynamic settings (`dynamic: true`) are also REQUIRED when they apply, but the value is pass-through (no closed-list validation); use the `recommended_value` if you do not want to discover an account-specific value via /v1/connections.", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean", "description": "When true, the setting must always be sent in /v1/query. Only one setting is declared required without a recommended_value: mailchimp.entity." }, "dynamic": { "type": "boolean", "description": "When true, the valid values are account-specific (discover via /v1/connections). The API does not validate the value against a closed list, but the setting is still REQUIRED when its applies_to_data_views matches." }, "multi_select": { "type": "boolean", "description": "When true, the value is a JSON array of strings (each validated against `options[]`)." }, "note": { "type": "string" }, "applies_to_data_views": { "type": "array", "items": { "type": "string" }, "description": "When present, the setting is REQUIRED only when the current data_view is in this list. When absent, the setting applies to every data_view of the integration." }, "recommended_value": { "description": "A value the upstream native API would typically apply when this setting is not explicitly customized. PROVIDED ONLY AS A RECOMMENDATION for clients that do not have a specific preference. The API does NOT inject this value automatically: the client must always include the setting in /v1/query when it applies (per `applies_to_data_views`). Reporting Ninja does not define the recommended_value; it mirrors the upstream API's documented default behavior.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "options": { "type": "array", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } }, "options_by_data_view": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } }, "description": "Per-data_view options map. Used when the valid values of a setting depend on the current data_view (e.g. pinterest_organic.pinterest_sort_by: 5 values for top_pins, 9 for top_video_pins)." } } }, "FiltersDescriptor": { "type": "object", "required": [ "supported" ], "description": "Describes the filter capabilities of an integration. Two shapes coexist: (a) integrations with a closed catalog of filter fields (e.g. facebook_ads, google_ads) expose `fields[]` with the operators valid for each filter field; (b) integrations with dynamic filter fields (e.g. ga4) expose `note`, `dimension_operators` and `metric_operators` and require the client to send `type_of_field` per filter.", "properties": { "supported": { "type": "boolean" }, "combination": { "type": "string", "enum": [ "and", "or", "and_or" ], "description": "How filters can be combined. `and` (facebook_ads, google_ads, microsoft_ads): all filters are AND-ed; the client must NOT send `combination` per filter (rejected for microsoft_ads). `and_or` (ga4): each filter may include `combination` (`AND` default, or `OR`); see ga4 notes for the iter 3 caveat about the second filter defining the group combination." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FilterField" }, "description": "Present for integrations with a closed catalog of filter fields." }, "note": { "type": "string", "description": "Free-text guidance for the client. Present for integrations with dynamic filter fields (e.g. ga4) or with no filter support (e.g. google_business_profile)." }, "dimension_operators": { "type": "array", "items": { "type": "string" }, "description": "Operators valid for dimension filters. Present for integrations with dynamic filter fields." }, "metric_operators": { "type": "array", "items": { "type": "string" }, "description": "Operators valid for metric filters. Present for integrations with dynamic filter fields." } } }, "FilterField": { "type": "object", "required": [ "id", "name", "category", "operators" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "operators": { "type": "array", "items": { "type": "string" } }, "allowed_values": { "type": "array", "items": { "type": "string" }, "description": "Closed list of valid filter values (case-sensitive). Present only for fields with a fixed enum (e.g. microsoft_ads CampaignStatus / AdDistribution / DeviceType). When present, every value sent in /v1/query.filters[].value MUST belong to this list (each element if value is an array)." }, "data_views": { "type": "array", "items": { "type": "string" }, "description": "List of data_view ids where this filter field is valid. Present for integrations where filter fields depend on the data_view (e.g. microsoft_ads). If absent, the field is valid for ALL data_views of the integration." } } }, "ConnectionsRequest": { "type": "object", "required": [ "integration_id" ], "properties": { "integration_id": { "type": "string" } } }, "Connection": { "type": "object", "required": [ "connection_key", "connection_name", "status" ], "properties": { "connection_key": { "type": "string" }, "connection_name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Connection status derived from the LAST KNOWN state of the underlying OAuth credentials. `active` = credentials were OK at the last refresh and queries are EXPECTED to succeed. `inactive` = credentials are known to be revoked, expired, in error state, pending re-authorization, or otherwise non-operational. For `cross_platform`, `active` requires ALL referenced credentials in the AccountsGroup to be OK; if ANY of them is not OK (or has been deleted), the group reports `inactive`. IMPORTANT: this field reflects the state as last observed by Reporting Ninja, NOT a real-time check against the external provider. After a connection is created, the transition from `active` to `inactive` happens ONLY when the user explicitly refreshes the connection in the data sources view of the Reporting Ninja UI and the refresh fails. As a consequence, a connection reported here as `active` may in practice already be unusable (for example, because the upstream OAuth grant has expired or been revoked by the user on the provider side) without that having been detected yet -- in such cases a /v1/query call will return an authorization-related error. Treat `active` as a positive but non-binding signal, not a guarantee." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } }, "Account": { "type": "object", "required": [ "account_id", "account_name" ], "properties": { "account_id": { "type": "string" }, "account_name": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code for monetary metrics of this account. Provided by 10 advertising integrations whose native APIs expose a per-account currency (facebook_ads, google_ads, microsoft_ads, linkedin_ads, tiktok_ads, pinterest_ads, snapchat_ads, reddit_ads, twitter_ads) plus ga4 (per-property currency). OMITTED for integrations without monetary metrics (organic social, mailchimp, search_console, business_profile) and for those without a native per-account currency (hubspot, cross_platform). Clients must NOT assume a default currency for omitted cases." } } }, "FieldsRequest": { "type": "object", "required": [ "integration_id" ], "properties": { "integration_id": { "type": "string" }, "connection_key": { "type": "string", "description": "REQUIRED only when include_custom_fields=true. MUST NOT be present when include_custom_fields is false or absent, and MUST NOT be present for integrations whose supports_custom_fields_per_account=false." }, "account_id": { "type": "string", "description": "REQUIRED only when include_custom_fields=true. MUST NOT be present when include_custom_fields is false or absent, and MUST NOT be present for integrations whose supports_custom_fields_per_account=false." }, "data_view": { "type": "string", "description": "Required when the integration exposes data_views. For example, REQUIRED for `google_ads` (use `integrated` for the cross-resource view, or one of the 20 specific data_views: `customer`, `campaign`, `ad_group`, `keyword_view`, etc.). NOT applicable to `facebook_ads`. Consult /v1/integrations/detail for the full list of valid values per integration." }, "include_custom_fields": { "type": "boolean", "default": false, "description": "Whether to include account-specific custom fields (custom conversions for facebook_ads, custom dimensions/metrics for ga4). Default false. Only allowed when the integration's catalog declares supports_custom_fields_per_account=true. When true, both connection_key and account_id are REQUIRED. When false or absent, connection_key and account_id MUST NOT be present in the request. The deprecated key `include_custom_conversions` is rejected with an error -- use `include_custom_fields` instead." } } }, "Field": { "type": "object", "required": [ "field_id", "field_name", "field_type", "dim_met" ], "properties": { "field_id": { "type": "string" }, "field_name": { "type": "string" }, "field_description": { "type": "string" }, "field_type": { "type": "string", "enum": [ "text", "number", "currency", "percent", "date", "date_month", "url", "country", "region", "hour" ], "description": "Public field type. NOTE for ga4 temporal dimensions (date, week, month): the value format in /v1/query responses depends on the query. (a) If the query has a single temporal dimension (\"trend\" mode), values come back with separators: `date` as YYYY-MM-DD (e.g. 2026-05-10), `month` as YYYY-MM (e.g. 2026-05), `week` as YYYY-MM-DD of the Monday of that week (e.g. 2026-04-13). (b) If the query has 2+ dimensions (non-trend), values come back in raw GA4 format with NO year prefix for week/month: `date` as YYYYMMDD (e.g. 20260512), `month` as MM (e.g. 05), `week` as WW (e.g. 20). NOTE for percent metrics (CTR, conversion rate, engagement rate, bounce rate, etc.): values come back in 0-100 scale (e.g. `1.22` means 1.22%). Divide by 100 client-side if a 0-1 representation is needed." }, "dim_met": { "type": "string", "enum": [ "dimension", "metric" ] } } }, "QueryRequest": { "type": "object", "required": [ "integration_id", "connection_key", "account_id", "fields", "date_range", "limit" ], "properties": { "integration_id": { "type": "string" }, "connection_key": { "type": "string" }, "account_id": { "type": "string" }, "data_view": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "date_range": { "$ref": "#/components/schemas/DateRange" }, "compare_to": { "$ref": "#/components/schemas/CompareRange" }, "comparison_type": { "type": "string", "enum": [ "percentage", "absolute", "value" ], "default": "percentage" }, "settings": { "type": "object", "additionalProperties": true, "description": "Per-request settings. Validated strictly server-side per integration: only keys declared in /v1/integrations/detail are accepted; any other key returns 400. Each setting that applies (per its applies_to_data_views) is REQUIRED; the API does NOT auto-inject defaults. See `Setting` schema and the catalog of each integration." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 50000 }, "cursor": { "type": "string", "nullable": true, "description": "Opaque cursor returned by a previous response as data.next_cursor. Submit verbatim to continue pagination. Cursors expire 3 hours after the original query; expired cursors return an error envelope with message 'paginated result expired, restart from page 1 without cursor'. Invalid cursors (different query or account) are silently ignored and pagination restarts from page 1. For async queries the same 3-hour cursor expiration applies, even if the job result is still available." }, "bypass_cache": { "type": "boolean", "default": false, "description": "If true, the API skips the cache lookup and always re-executes the query against the upstream platform. The fresh result is still written to the cache (so subsequent queries with the same input benefit). Useful when the client needs guaranteed-fresh data. Applies to both /v1/query (sync) and /v1/query/async." } } }, "DateRange": { "type": "object", "required": [ "preset" ], "properties": { "preset": { "type": "string", "enum": [ "today", "yesterday", "lastweeksunsat", "lastweekmonsun", "thismonth", "thismonthtoyesterday", "lastmonth", "thisyear", "lastyear", "lastyeartodate", "lastxdays", "lastxweeks", "lastxweeksiso", "lastxmonths", "lastxyears", "custom" ] }, "x": { "type": "integer", "description": "Required for lastx* presets." }, "include_current": { "type": "boolean", "description": "Optional for lastxmonths." }, "start": { "type": "string", "format": "date", "description": "Required for custom." }, "end": { "type": "string", "format": "date", "description": "Required for custom." } } }, "CompareRange": { "type": "object", "required": [ "preset" ], "properties": { "preset": { "type": "string", "enum": [ "none", "previous", "year_ago", "year_ago_match_weekday", "custom" ] }, "start": { "type": "string", "format": "date", "description": "Required for custom." }, "end": { "type": "string", "format": "date", "description": "Required for custom." } } }, "Filter": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "description": "Filter field id from /v1/integrations/detail or /v1/fields." }, "operator": { "type": "string", "description": "Public operator. The valid set depends on integration: for facebook_ads / google_ads see /v1/integrations/detail.filters.fields[].operators per filter field; for ga4 see /v1/integrations/detail.filters.dimension_operators or metric_operators depending on the filter's type_of_field." }, "value": { "description": "Scalar or array depending on the operator. For ga4 IN_LIST/NOT_IN_LIST and google_ads multi-value operators arrays are accepted; for scalar operators arrays are rejected. For metric filters in ga4 the value must be numeric." }, "type_of_field": { "type": "string", "enum": [ "dimension", "metric" ], "description": "Required by integrations whose filter catalog declares it (e.g. ga4 -- dimension or metric; and linkedin_ads/tiktok_ads/pinterest_ads/snapchat_ads/reddit_ads -- dimension). Declares whether the field is a dimension or a metric so the right operator set is validated. Other integrations derive it internally and do not accept it; see /v1/integrations/detail for the rule per integration." }, "combination": { "type": "string", "enum": [ "AND", "OR" ], "description": "Optional combination of this filter with the previous one. Default \"AND\". OR support varies by integration: ga4 accepts AND and OR; linkedin_ads/tiktok_ads/pinterest_ads/snapchat_ads/reddit_ads are OR-only (AND is rejected); facebook_ads, google_ads and the rest force AND. See /v1/integrations/detail for the rule per integration. When 2+ filters are sent, the combination of the second filter defines the combination of the whole group." } } }, "AsyncQueryAcceptedResponse": { "type": "object", "description": "Envelope returned by POST /v1/query/async. The `data.job_id` is the opaque identifier to pass to /v1/query/status when polling for the result.", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string", "description": "Opaque identifier of the persisted async query job. Pass this to /v1/query/status to poll for the result.", "example": "1234567890" }, "status": { "type": "string", "enum": [ "pending" ], "description": "Initial state of the job after submission. Transitions to running -> success/error as the executor processes it." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AsyncQueryStatusResponse": { "type": "object", "description": "Envelope returned by POST /v1/query/status. When `data.status` is `success`, `data.result` embeds the same `{status, data.rows[], meta}` body that /v1/query would have produced. When `data.status` is `error`, `data.error_message` describes the failure.", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "required": [ "job_id", "status" ], "properties": { "job_id": { "type": "string", "example": "1234567890" }, "status": { "type": "string", "enum": [ "pending", "running", "success", "error" ], "description": "Current state. `pending`: awaiting processing. `running`: executing. `success`: completed; see data.result. `error`: completed with failure; see data.error_message." }, "created_at": { "type": "integer", "format": "int64", "description": "UNIX epoch milliseconds when the job was submitted." }, "started_at": { "type": "integer", "format": "int64", "description": "UNIX epoch milliseconds when the executor started. Only present when status is running/success/error." }, "completed_at": { "type": "integer", "format": "int64", "description": "UNIX epoch milliseconds when the executor completed (with success or error). Only present when status is success/error." }, "result": { "type": "object", "description": "Embedded /v1/query response body (status + data.rows[] + meta). Same shape as the synchronous /v1/query response. Only present when status is success." }, "error_message": { "type": "string", "description": "Truncated error description (<= 500 chars). Only present when status is error." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }