v2
latestOpenAPI 3.1.02026-08-075421692.0 MBFlexible 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).
Query parameters
Zernio SocialAccount id (posting or ads variant); its platform selects the Meta or Google contract.
Meta only (required there): insights node — act_<n>, campaign id, ad set id or ad id.
Google only (required there): the GAQL SELECT statement to run.
Google 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
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.
End of range (YYYY-MM-DD); requires fromDate.
Days per row (1-90), monthly, or all_days.
Rows per page
Cursor from paging.after of the previous page.
Response
Insight rows (raw platform shape)