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. adAccountId (alias 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).
Queries run against Google Ads API v25, so write GAQL against the v25 field reference. One exception is translated for backward compatibility: the legacy campaign.start_date / campaign.end_date (removed by Google in v23) are rewritten to campaign.start_date_time / campaign.end_date_time, and rows still carry campaign.startDate / campaign.endDate as YYYY-MM-DD. In WHERE, =, <, <=, >, >=, BETWEEN and IS [NOT] NULL against a 'YYYY-MM-DD' literal are translated; any other form returns Google's 400. New code should select the _date_time fields directly.
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: platform ad account ID (Google customer ID, digits only) when the connection has several Google Ads accounts.
Alias of adAccountId, kept for existing callers
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. Pass none to clear Meta's default action_type breakdown, required to combine some non-action breakdowns such as instagram_ads_follow_type (otherwise Meta returns a (#100) invalid-combination error).
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)