ChatGPT AdsGET Ads Prompts

ChatGPT Ads Prompts

Tracked prompts that triggered ChatGPT ads for a domain, paginated, with per-prompt ad rate and competitors.

curl --request GET \
  --url 'https://api.aiclicks.io/api/v1/ads/prompts?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3&days=30&page=1&per_page=50' \
  --header 'Authorization: Bearer ak_live_xxx'
{
  "data": {
    "prompts": [
      {
        "id": "b0a1c9d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
        "prompt": "best analytics tool for startups",
        "topic": "Analytics",
        "yourBrandAppeared": true,
        "adRateNum": 7,
        "adRateDen": 8,
        "competitors": ["globex", "initech"],
        "cardsTotal": 21,
        "lastRun": "3h ago"
      },
      {
        "id": "c1b2d3e4-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
        "prompt": "cheapest crm for small business",
        "topic": null,
        "yourBrandAppeared": false,
        "adRateNum": 4,
        "adRateDen": 8,
        "competitors": ["hooli"],
        "cardsTotal": 9,
        "lastRun": "Jun 14"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_count": 42,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false,
      "last_page": true
    }
  },
  "domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
  "days": 30,
  "generated_at": "2026-06-17T10:00:11.218Z"
}

Returns the tracked prompts that drew ads inside ChatGPT during the lookback window, one row per prompt, paginated. Each row reports how often that prompt's ChatGPT responses carried ads (adRateNum / adRateDen), which competitor brands advertised on it, how many cards were seen, and whether your own brand appeared. Use it to answer "which of my prompts are advertising battlegrounds, and who's fighting for them?" in one call.

Rows are sorted by cardsTotal descending (ties broken by ad rate, then prompt text). Only prompts with at least one ad in the window are included.

domain_id is a required query parameter. Use GET /api/v1/domains to discover which domains the calling key can access.

Authorizations

header
Authorizationstring
Required

Your API key formatted as Bearer ak_live_<your-key>. Create one in the dashboard under Settings → Developers.

header
X-Request-Idstring

Optional UUID for log correlation. If omitted, we generate one and echo it back in the response.

Query parameters

query
domain_idstring
Required

UUID of the domain. Find domains via GET /api/v1/domains. Omitting this returns 400.

query
daysinteger

Look-back window, 1–365. Defaults to 30.

query
pageinteger

1-based page number. Defaults to 1. Must be ≥ 1.

query
per_pageinteger

Rows per page, 1–500. Defaults to 50.

Response

dataobject
Required

The prompts payload plus pagination metadata.

data.promptsarray
Required

One row per tracked prompt that drew ads, sorted by cardsTotal descending (ties broken by adRateNum descending, then prompt text). This is the current page slice, not the full set.

data.paginationobject
Required

Pagination metadata for the prompts slice.

domain_idstring
Required

Echo of the requested domain.

daysinteger
Required

Echo of the requested window.

generated_atstring
Required

ISO-8601 timestamp of when the server produced (or cached) this response.

Response headers

HeaderDescription
X-CacheHIT or MISS. Indicates whether the response came from cache.
X-Request-IdUnique request id. Echoes incoming if you set one.
X-RateLimit-LimitMax requests per minute for this key.
X-RateLimit-RemainingRequests remaining in current minute.
X-RateLimit-ResetUnix epoch seconds when the window resets.

Caching

Cached for 30 minutes server-side per (domain_id, days, page, per_page). Newly completed analyses appear after the TTL expires.

Errors

400 Bad Requesterror

domain_id query parameter missing. Body points you at /api/v1/domains.

401 Unauthorizederror

Missing, malformed, or revoked API key.

403 Forbiddenerror

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.

404 Not Founderror

domain_id is malformed, does not exist, or your user is not a member of its team.

429 Too Many Requestserror

Rate limit exceeded. Inspect the Retry-After header for how long to wait.

Empty result

If no prompts drew ads in the window, the response is a successful 200 with an empty list and zeroed pagination:

{
  "data": {
    "prompts": [],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_count": 0,
      "total_pages": 0,
      "has_next": false,
      "has_prev": false,
      "last_page": true
    }
  },
  "domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
  "days": 30,
  "generated_at": "2026-06-17T10:00:11.218Z"
}