Flexible live insights query
Live, flexible insights query. The account's platform picks the contract:
Meta (facebook/instagram): forwards caller-chosen fields, breakdowns and filtering
to any Meta insights node and returns Meta's rows verbatim. objectId (required) selects the
node; level sets row granularity. Semantic validation is Meta's: an unknown field or invalid
breakdown combination returns a 400 carrying Meta's message. For long ranges or agency-scale
accounts prefer the async variant (POST /v1/ads/insights/reports).
Google Ads (googleads): raw GAQL passthrough. Send any read-only GAQL SELECT via query
(campaign/keyword/search-term/geo/demographic/asset/shopping resources, change_event, any
segments.*) and rows come back verbatim (camelCase, counters as strings). Results are paged
at a fixed 10,000 rows; follow paging.nextPageToken with pageToken. customerId is only
needed when the connection has several Google Ads accounts. Semantic validation is Google's:
an invalid query returns a 400 carrying Google's message (note: selecting segments.date
requires a finite date filter).
Authorization
bearerAuth API key authentication - use your Zernio API key as a Bearer token
In: header
Query Parameters
Zernio SocialAccount id (posting or ads variant); its platform selects the Meta or Google contract.
Meta only (required there): insights node — act_, campaign id, ad set id or ad id.
Google only (required there): the GAQL SELECT statement to run.
length <= 10000Google only: numeric customer id (no dashes) when the connection has several Google Ads accounts.
Google only: cursor from paging.nextPageToken of the previous page.
Row granularity
Value in
- "ad"
- "adset"
- "campaign"
- "account"
Comma-separated Graph insights fields (e.g. spend,impressions,frequency,website_purchase_roas). Omitted = Meta's default set.
Comma-separated Graph breakdowns (e.g. age,gender or publisher_platform).
Comma-separated Graph action breakdowns. Segments the actions[] arrays in each row.
Comma-separated Meta attribution windows. Action values are returned keyed per window.
When actions are counted: impression, conversion or mixed.
Use the ad sets' own attribution settings for action counting.
JSON array of Meta filter objects: [{"field", "operator", "value"}]. Applied server-side by Meta.
Meta date_preset (e.g. last_7d, last_30d, this_month). Mutually exclusive with fromDate/toDate.
Start of range (YYYY-MM-DD); requires toDate.
dateEnd of range (YYYY-MM-DD); requires fromDate.
dateDays per row (1-90), monthly, or all_days.
Rows per page
1 <= value <= 50025Cursor from paging.after of the previous page.
Response Body
application/json
application/json
{ "objectId": "string", "customerId": "string", "fieldMask": "string", "data": [ {} ], "paging": { "after": "string", "nextPageToken": "string" }}Generate keyword ideas (Google Keyword Planner)
Google Ads only. Runs Keyword Planner's generateKeywordIdeas from seed keywords, a seed URL, or both, returning idea rows verbatim (avgMonthlySearches, competition, competitionIndex, top-of-page bid micros, monthlySearchVolumes). Counters are int64s encoded as strings; bid values are micros of the account currency. Omitting `countries` targets worldwide.
List conversion actions and their tag snippets
Lists Google Ads conversion actions on the resolved customer, all types by default. Each action's `tagSnippets` (global site tag + event snippet) is included when Google has them for that action's type, e.g. `WEBPAGE`. Google-only; other platforms return `501`. Requires the Ads add-on. `customerId` is optional: when omitted, it is resolved from the connection's accessible Google Ads customers, and the call fails with `400` when more than one is accessible (pass `customerId` to disambiguate). The list itself is cached for the quota window (1 hour fresh, up to 7 days last-good; the cache key does not vary on `type`). The response carries `cachedAt` and `stale`, set when a quota-exhausted call falls back to the last-good copy instead of a live read.