ChatGPT Ads Read
Full performance reporting at any scope: ad_account, campaign, ad_group, or ad (pass scope + scope_id)
POST https://api.adspirer.ai/api/v1/tools/get_chatgpt_insights/execute
Authorization: Bearer sk_live_... — your Adspirer API key (required)Content-Type: application/json (required)Idempotency-Key: <uuid> — recommended for write operations to make retries safeAll tool arguments are wrapped in an arguments object.
| Field | Type | Description |
|---|---|---|
scope | string optional | 'ad_account', 'campaign', 'ad_group', or 'ad'. default: "ad_account" |
scope_id | string optional | Required for campaign/ad_group/ad scopes — the cmpn_/adgrp_/ad_ id. |
lookback_days | integer optional | How many days back to report (used unless start/end are given). default: 30 |
start | integer optional | Explicit window start (unix seconds, floored to the hour). Use with end instead of lookback_days. |
end | integer optional | Explicit window end (unix seconds, floored to the hour). |
breakdown | string optional | Time granularity: 'none', 'hourly', 'daily', or 'monthly'. (hourly not allowed with segments.) default: "none" |
aggregation_level | string optional | Row entity within the scope: 'ad_account', 'campaign', 'ad_group', or 'ad' (e.g. ad_account scope + campaign level = per-campaign rows). |
segments | array optional | At most ONE breakdown: 'product', 'country', 'device', or 'platform'. 'platform' splits by ChatGPT surface (android_app / android_web / desktop_web / ios_app / ios_web / web). Hourly granularity is not allowed together with a segment. |
fields | array optional | Project specific metric columns (the API only returns a metric when asked). Available: impressions, clicks, spend, ctr, cpc, cpm, conversions, post_click_cvr, cpa, click_through_conversions, view_through_conversions, order_created_roas, order_created_attributed_sales, carousel_product_card_impressions, carousel_product_card_clicks. Omit for the default set (impressions + row name). |
filters | array optional | Row filters: [{field, operator, value}] with operator 'IN' (array value), 'GREATER_THAN', or 'LESS_THAN' (numeric). E.g. {'field':'spend','operator':'GREATER_THAN','value':100}. |
sort | array optional | Ordering: [{field, direction}] with direction 'asc'|'desc'. E.g. {'field':'clicks','direction':'desc'}. |
includes | array optional | Zero-impression expansion: 'zero_impression_items' (no segments) or 'zero_impression_products' (with product segment). |
limit | integer optional | Max rows per page (1–2000). default: 200 |
after | string optional | Pagination cursor — pass the prior response's last_id to get the next page. |
before | string optional | Pagination cursor — pass the prior response's first_id to page backward. |
raw_data | boolean optional | Return the full raw insights JSON instead of the formatted table. default: false |
{
"arguments": {
"scope": "ad_account",
"scope_id": "string",
"lookback_days": 30,
"start": 1,
"end": 1,
"breakdown": "none"
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for get_chatgpt_insights)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "get_chatgpt_insights"
}
{
"success": false,
"error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n - Acme Holdings (ad_account_id=\"act_123456789\")\n - Acme EU (ad_account_id=\"act_987654321\")",
"is_error": true,
"tool": "get_chatgpt_insights"
}
{
"success": false,
"error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
"is_error": true,
"tool": "get_chatgpt_insights",
"quota": {
"used": 150,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01",
"upgrade_url": "https://adspirer.ai"
}
}
Interactive: Swagger UI
Machine-readable: OpenAPI 3.1 spec · llms-full.txt
More tools: ChatGPT Ads · All tools
Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai