OpenAI ChatGPT Ads — Insights

Answer performance questions via the get_insights tool.

Request

The user's question: $ARGUMENTS

How the insights API thinks

• level picks the scope path: ad_account (whole account), or campaign / ad_group / ad with an entity_id.
• aggregation_level picks the row granularity within that scope — the ranking trick: level="ad_account", aggregation_level="ad", sort_field="clicks", limit=5 = top 5 ads account-wide.
• time_granularity: "none" for totals, "daily" for trend rows.
• since/until: YYYY-MM-DD. Metrics: impressions, clicks, spend, ctr, cpc, cpm.

Workflow

1. get_ad_account once for currency and account name.
2. Map the question to one or two get_insights calls (scope → aggregation → time range → sort). "Best/worst X" → sort by the metric they care about; default clicks.
3. Resolve names: insights rows carry ids — when the user thinks in names, cross-reference list_campaigns/list_ads.
4. Answer in plain language first (one sentence with the number that answers the question), then a compact table. State the date range you actually queried. Flag low-volume rows (<100 impressions) as too thin to compare.

Anti-patterns

• Dumping raw JSON instead of answering the question asked.
• Comparing CTRs across rows with wildly different impression counts without saying so.
• Inventing metrics the API doesn't return (no conversions in insights today — that's the Conversions API, not yet covered by this server).
• Forgetting that spend figures are in the account currency.