ChatGPT Ads KPIs
Headline advertising metrics for a tracked domain — how often ads showed up inside ChatGPT answers, with deltas vs the previous window.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/ads/kpis?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3&days=30' \
--header 'Authorization: Bearer ak_live_xxx'
import httpx, os
resp = httpx.get(
"https://api.aiclicks.io/api/v1/ads/kpis",
params={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
kpis = resp.json()["data"]
print(f"{kpis['promptsWithAds']} / {kpis['totalPrompts']} prompts drew ads "
f"({kpis['promptsWithAdsDelta']:+}% vs previous window)")
print(f"your brand appeared on {kpis['brandAppeared']} prompts "
f"({kpis['brandAppearedDelta']:+} {kpis['brandAppearedDeltaLabel']})")
const url = new URL("https://api.aiclicks.io/api/v1/ads/kpis");
url.searchParams.set("domain_id", "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3");
url.searchParams.set("days", "30");
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.AICLICKS_API_KEY}` },
});
const { data } = await resp.json();
console.log(`${data.promptsWithAds} / ${data.totalPrompts} prompts drew ads`);
console.log(`unique advertisers: ${data.uniqueAdvertisers} (${data.advertiserExits} exited)`);
{
"data": {
"promptsWithAds": 42,
"totalPrompts": 118,
"promptsWithAdsDelta": 16.7,
"brandAppeared": 9,
"brandAppearedDelta": 3,
"brandAppearedDeltaLabel": "vs previous window",
"uniqueAdvertisers": 27,
"advertiserExits": 4,
"totalCardsSeen": 311,
"totalCardsDelta": 58,
"totalCardsDeltaLabel": "vs previous window"
},
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"generated_at": "2026-06-17T10:00:11.218Z"
}
{
"detail": "domain_id query parameter is required. List the domains this key can access with GET /api/v1/domains, then pass ?domain_id=<uuid>."
}
{
"detail": "Invalid or revoked API key"
}
{
"detail": "API access is not enabled for this team. Contact support@aiclicks.io."
}
{
"detail": "Domain not found"
}
{
"detail": "Too many requests. Please try again later."
}
Returns the headline numbers for advertising that surfaced inside ChatGPT's answers to your domain's tracked prompts over the lookback window: how many prompts drew ads, how often your own brand appeared, how many distinct advertisers competed, and how many ad cards were seen in total. Each count ships with a delta computed against the immediately preceding window of the same length. Use it to answer "is ChatGPT showing ads on my prompts, and is that growing?" in one call.
domain_id is a required query parameter. Use `` to discover which domains the calling key can access.
Authorizations
Your API key formatted as Bearer ak_live_<your-key>. Create one in the dashboard under Settings → Developers.
Optional UUID for log correlation. If omitted, we generate one and echo it back in the response.
Query parameters
UUID of the domain. Find domains via ``. Omitting this returns 400.
Look-back window, 1–365. Defaults to 30. Deltas compare this window against the immediately preceding window of the same length — a days=30 request compares the last 30 days against the 30 days before that.
Response
The KPI payload. All counts are for the current window; every *Delta field measures change against the previous equal-length window.
Number of distinct tracked prompts where at least one ad appeared in a ChatGPT response during the window.
Total analyzable prompts tracked for the domain. Denominator for the "share of prompts with ads" ratio; not filtered by the window.
Percentage change in promptsWithAds vs the previous window, rounded to one decimal. When the previous window had zero, this is 100.0 if the current window is positive, otherwise 0.0.
Number of prompts where your brand was one of the advertisers (matched against the domain's own host).
Absolute change in brandAppeared vs the previous window (a count difference, not a percentage). Can be negative.
Human-readable label for the delta. Currently always "vs previous window".
Count of distinct advertiser brands seen across all prompts in the current window.
Count of advertisers present in the previous window but absent from the current one. Never negative.
Total ad cards (individual creatives) observed across every advertiser and response in the current window. A prompt with three advertisers each showing two cards contributes six.
Absolute change in totalCardsSeen vs the previous window (a count difference). Can be negative.
Human-readable label for the delta. Currently always "vs previous window".
Echo of the requested domain.
Echo of the requested window.
ISO-8601 timestamp of when the server produced (or cached) this response.
Response headers
| Header | Description |
|---|---|
X-Cache | HIT or MISS. Indicates whether the response came from cache. |
X-Request-Id | Unique request id. Echoes incoming if you set one. |
X-RateLimit-Limit | Max requests per minute for this key. |
X-RateLimit-Remaining | Requests remaining in current minute. |
X-RateLimit-Reset | Unix epoch seconds when the window resets. |
Caching
Cached for 30 minutes server-side per (domain_id, days). Newly completed analyses appear after the TTL expires.
Errors
domain_id query parameter missing. Body points you at /api/v1/domains.
Missing, malformed, or revoked API key.
Team's developer_access flag is off, the domain belongs to a team your API key is not scoped to, or your allowed_domains allowlist excludes it.
domain_id is malformed, does not exist, or your user is not a member of its team.
Rate limit exceeded. Inspect the Retry-After header for how long to wait.
Empty result
If no analyses ran in the window, the response is still a successful 200 with zeroed counts:
{
"data": {
"promptsWithAds": 0,
"totalPrompts": 118,
"promptsWithAdsDelta": 0.0,
"brandAppeared": 0,
"brandAppearedDelta": 0,
"brandAppearedDeltaLabel": "vs previous window",
"uniqueAdvertisers": 0,
"advertiserExits": 0,
"totalCardsSeen": 0,
"totalCardsDelta": 0,
"totalCardsDeltaLabel": "vs previous window"
},
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"generated_at": "2026-06-17T10:00:11.218Z"
}