Competitor Citations
How often AI answers cite the website of the brand and of each tracked competitor, with the share of all citations.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/competitor-citations?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3&days=30&model=ChatGPT' \
--header 'Authorization: Bearer ak_live_xxx'
import httpx, os
resp = httpx.get(
"https://api.aiclicks.io/api/v1/competitor-citations",
params={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"topic_ids": ["c0ffee00-0000-4000-8000-000000000001"],
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
for row in resp.json()["data"]["items"]:
print(row["name"], row["citations"], row["share_of_all_citations"])
const url = new URL("https://api.aiclicks.io/api/v1/competitor-citations");
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.table(data.items);
{
"data": {
"items": [
{
"id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Northwind",
"website": null,
"is_brand": true,
"citations": 412,
"share_of_all_citations": 6.84
},
{
"id": "f6a7b8c9-3333-4eee-8fff-000000000001",
"name": "Acme Rival",
"website": "acmerival.com",
"is_brand": false,
"citations": 287,
"share_of_all_citations": 4.77
},
{
"id": "f6a7b8c9-3333-4eee-8fff-000000000002",
"name": "Globex",
"website": "globex.example",
"is_brand": false,
"citations": 95,
"share_of_all_citations": 1.58
}
]
},
"generated_at": "2026-11-09T09:30:00.118Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all"
}
{
"detail": "Dates must be YYYY-MM-DD."
}
{
"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."
}
This endpoint compares citations across the tracked brands of a domain. It returns one row for the own brand and one row for each tracked competitor. Each row has the number of cited URLs on that website and its share of all citations in the window.
The own brand is always first. The competitors follow, from the most citations to the fewest.
Use this endpoint to answer the question "Whose website do AI answers cite most?". For the same data for each topic or tag, use GET /api/v1/citation-share. For all cited websites, including third-party sites, use GET /api/v1/citation-domains.
Authorizations
Your API key in the format Bearer ak_live_<your-key>. Create a key in the dashboard under Settings → Developers.
An optional UUID for log correlation. If you do not send one, the server makes one and returns it in the response.
Query parameters
The UUID of the domain. Find domains with GET /api/v1/domains.
The look-back window in days, from 1 to 365. The default is 30. The server uses the exact value. It does not round it to a fixed bucket.
The first day of a fixed window, in the format YYYY-MM-DD. Send it with end_date. When you send both dates, they replace days.
The last day of a fixed window, in the format YYYY-MM-DD. The day is included. A window can be at most 365 days.
One AI channel by its generic name, for example ChatGPT, Perplexity, Gemini, AI Overviews, AI Mode, Claude, Microsoft Copilot or Grok. The default is all.
Topic UUIDs from GET /api/v1/topics. Repeat the parameter for each value, for example topic_ids=a&topic_ids=b. The endpoint then counts only the prompts in these topics.
Tag UUIDs from GET /api/v1/tags. Repeat the parameter for each value. If you send topic_ids and tag_ids, the endpoint counts the prompts that match either filter.
Set true to skip the cache and calculate the result again. The new result replaces the cached result. The default is false.
Response
The citation counts.
One row for the own brand, then one row for each tracked competitor.
The ISO-8601 time when the server made (or cached) this response.
The domain from the request.
The days value from the request.
The model value from the request.
Response headers
| Header | Description |
|---|---|
X-Cache | HIT, MISS or REFRESH. REFRESH means that you sent fresh=true. |
X-Request-Id | The request id. If you sent one, the server returns it. |
X-RateLimit-Limit | The maximum number of requests per minute for this key. |
X-RateLimit-Remaining | The number of requests that remain in this minute. |
X-RateLimit-Reset | The Unix time in seconds when the window starts again. |
Caching
The server caches the response for 1 hour for each set of parameters. To get new data before the cache expires, send fresh=true.
Errors
A date is not in the format YYYY-MM-DD, start_date is after end_date, or the window is longer than 365 days. If domain_id is missing or days is out of range, the endpoint returns 422.
The API key is missing, malformed or revoked.
The developer_access flag of the team is off. Or the domain is not in the scope of your key, or your allowed_domains list does not include it.
The domain_id is malformed or does not exist, or your user is not a member of its team.
You sent too many requests. Read the Retry-After header to know how long to wait.
Empty result
If the topic_ids or tag_ids filters match no prompts, the endpoint returns 200 with an empty list:
{
"data": { "items": [] },
"generated_at": "2026-11-09T09:30:00.118Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all"
}