OpenAI Ads insights
openai_ads_insightsQuery OpenAI Ads performance over a date range, including impressions, clicks, spend, CTR, conversions, and attributed sales for an account, campaign, ad group, or ad.
Instructions
OpenAI Ads (ChatGPT ads) performance over a date range: impressions, clicks, spend, ctr, conversions and attributed sales for the ad account or one campaign, ad group or ad. Returns "rows" as reported (flat keys such as campaign_id; null kept, null_means "non calculable"), recomputed "totals" (roas = sum of sales / sum of spend), "currency" (from order_created_attributed_sales_currency, else None), "date_range" in the timezone returned by the API, "next_after" while has_more (reads up to max_rows rows over at most 5 pages), units (spend in major currency units, ctr ratio) and "attribution". No automatic retry.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Optional sort criteria in order: [{"field": "spend", "direction": "desc"}] (at most 5) | |
| after | No | next_after (last_id) of a previous call to read the next rows; empty to start | |
| level | No | Which endpoint: account = the whole ad account; campaign, ad_group or ad = one entity given by entity_id | account |
| before | No | first_id of a previous call to read the rows before it (one page); not with after | |
| fields | No | Canonical field names, e.g. impressions, clicks, spend, ctr, cpc, cpm, conversions, cpa, post_click_cvr, order_created_attributed_sales, order_created_attributed_sales_currency, order_created_roas, campaign.id, campaign.name, metadata.readable_time, metadata.timezone; empty for these metrics plus metadata.timezone | |
| filters | No | Optional filters, combined with AND: {"field": "campaign.id", "operator": "IN", "value": ["cmpn_1"]} or {"field": "ad.clicks", "operator": "GREATER_THAN" or "LESS_THAN", "value": 10} (at most 10) | |
| segment | No | Optional single segment: product, country, device or platform (request segment fields such as country.clicks) | |
| end_date | Yes | Last day, YYYY-MM-DD (inclusive) | |
| max_rows | No | Maximum rows returned by this call (1 to 6000), over at most 5 pages | |
| timezone | No | Optional IANA timezone of the day boundaries; empty uses the ad account timezone (keep empty for conversion or sales metrics, which require whole days in the account timezone) | |
| client_id | No | Client id from clients_list; empty uses the only client (or the environment variables without a registry) | |
| entity_id | No | Id of the campaign, ad group or ad (letters, digits, _ and -); empty for level account | |
| page_size | No | Rows per API page (1 to 2000) | |
| start_date | Yes | First day, YYYY-MM-DD | |
| time_granularity | No | none: one row per entity for the period; daily, monthly or hourly (hourly: about 30 days of history, not with a segment) | none |
| aggregation_level | No | Row entity inside the endpoint scope: ad_account, campaign, ad_group or ad; empty uses the endpoint level | |
| attribution_time_basis | No | ad_event_time (API default) or conversion_time; empty sends nothing | |
| attribution_window_days | No | Click attribution window in days: 7, 14 or 30 | |
| include_zero_impression_items | No | True: also return entities with zero impressions (only without a segment) | |
| view_through_attribution_window_days | No | View-through attribution window in days: 0 or 1 |