chatgpt_ads_get_insights

Get ChatGPT Ads Insights

Chatgpt

Description

Delivery reporting for the ChatGPT Ads account: impressions, clicks, spend, ctr, cpc, cpm. These six are the only metrics the API exposes. This is the performance report for ChatGPT Ads — there is no separate report tool on this server. Scope vs rows: \

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "chatgpt_ads_get_insights",
    "arguments": {
      "level": "ad_account",
      "aggregation_level": "campaign",
      "reason": "Monthly performance review"
    }
  }
}

Parameters

NameTypeRequiredDescription
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (15)
NameTypeRequiredDescription
level string Optional Scope of the report. "ad_account" covers the whole account; the others need entity_id.
ad_account campaign ad_group ad
entity_id string Optional Campaign, ad group, or ad ID to scope to. Required unless level is "ad_account".minLength: 1, maxLength: 64, pattern: ^[A-Za-z0-9_-]+$
aggregation_level string Optional What each row represents. Must be at or below level. Defaults to level.
ad_account campaign ad_group ad
time_granularity string Optional Time bucket per row. "none" returns one row per entity for the whole window. Segmented requests do not support "hourly".
hourly daily monthly none
date_since string Optional Start date (YYYY-MM-DD) in the ad account timezone. Defaults to 30 days before date_until.pattern: ^\d{4}-\d{2}-\d{2}$
date_until string Optional End date (YYYY-MM-DD) in the ad account timezone. Defaults to today.pattern: ^\d{4}-\d{2}-\d{2}$
fields array Optional Canonical dotted field names, e.g. ["campaign.name","campaign.spend"]. Defaults to ids, name, and all six metrics for the aggregation level.
filters array Optional Filters, ANDed together. E.g. [{"field":"campaign.id","operator":"IN","value":["cmpn_1"]}].
sort array Optional Sort order, applied before pagination. E.g. [{"field":"campaign.spend","direction":"desc"}].
segment string Optional Extra breakdown dimension. Only available on enabled ad accounts; segmented requests cannot use hourly granularity.
product country device
include_zero_impressions boolean Optional Include entities with no impressions in the window.
include_conversions boolean Optional Also fetch attributed conversion totals per entity. Whole-window totals only, not per time bucket. Account-gated: if unavailable the delivery data is still returned.
limit integer Optional Maximum rows to return (1–2000). Default: 100.min: 1, max: 2000
cursor string Optional Opaque pagination cursor from a previous response.
connection_id string Optional Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs.

Examples

Last 30 days by campaign

{
  "level": "ad_account",
  "aggregation_level": "campaign",
  "reason": "Monthly performance review"
}

hopkin chatgpt insights get --level ad_account --aggregation-level campaign

Specific window

{
  "level": "ad_account",
  "aggregation_level": "campaign",
  "date_since": "2026-07-01",
  "date_until": "2026-07-31",
  "reason": "July report"
}

hopkin chatgpt insights get --level ad_account --aggregation-level campaign --date-since 2026-07-01 --date-until 2026-07-31

Top ads by clicks

{
  "level": "ad_account",
  "aggregation_level": "ad",
  "sort": [
    {
      "field": "ad.clicks",
      "direction": "desc"
    }
  ],
  "limit": 10,
  "reason": "Find best performing creatives"
}

hopkin chatgpt insights get --level ad_account --aggregation-level ad --sort [object Object] --limit 10

With conversions

{
  "level": "ad_account",
  "aggregation_level": "campaign",
  "include_conversions": true,
  "reason": "Calculate cost per conversion"
}

hopkin chatgpt insights get --level ad_account --aggregation-level campaign --include-conversions true