ChatGPT Ads Read
List ad groups under a ChatGPT Ads campaign, with status, billing event, and max bid (in the account currency)
POST https://api.adspirer.ai/api/v1/tools/list_chatgpt_ad_groups/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 |
|---|---|---|
query | string optional | Free-text search across name, id, description (and ad copy for ads). Case-insensitive substring. |
status_filter | string optional | Filter by status — comma-separated (e.g. 'active' or 'active,paused'). Omit for all. |
type_filter | string optional | Filter by bidding_type — comma-separated 'impressions','clicks','conversions'. (Campaigns only.) |
start_after | string optional | Only rows starting on/after this date (YYYY-MM-DD). |
end_before | string optional | Only rows starting on/before this date (YYYY-MM-DD). |
sort_by | string optional | Sort by any field: e.g. 'name', 'status', 'budget', 'daily_budget'. |
sort_order | string optional | 'asc' or 'desc'. default: "asc" |
offset | integer optional | Pagination offset (skip this many matching rows). default: 0 |
limit | integer optional | Max rows to return per page (after filtering). default: 50 |
campaign_id | string required | Parent campaign ID |
{
"arguments": {
"campaign_id": "<campaign_id>",
"query": "string",
"status_filter": "string",
"type_filter": "string",
"start_after": "string",
"end_before": "string",
"sort_by": "string"
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for list_chatgpt_ad_groups)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "list_chatgpt_ad_groups"
}
{
"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": "list_chatgpt_ad_groups"
}
{
"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": "list_chatgpt_ad_groups",
"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