Topic Metrics
Get one scorecard for each topic: prompts, answers, visibility, mentions, position, citations, sentiment and search volume.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/topic-metrics?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/topic-metrics",
params={"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3", "days": 30},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
# Topics with the lowest visibility first.
for topic in sorted(resp.json()["data"]["items"], key=lambda t: t["avg_visibility"]):
print(topic["avg_visibility"], topic["name"])
const url = new URL("https://api.aiclicks.io/api/v1/topic-metrics");
url.searchParams.set("domain_id", "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3");
url.searchParams.set("model", "ChatGPT");
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": "d4c3b2a1-0000-4aaa-8bbb-000000000010",
"name": "Inventory Software",
"query_count": 25,
"answers_count": 3480,
"avg_visibility": 5,
"total_mentions": 168,
"avg_position": 6.2,
"citation_count": 47078,
"brand_citation_count": 149,
"avg_sentiment": 0,
"avg_volume": 11330
},
{
"id": "d4c3b2a1-0000-4aaa-8bbb-000000000011",
"name": "Warehouse Operations",
"query_count": 12,
"answers_count": 1669,
"avg_visibility": 4,
"total_mentions": 75,
"avg_position": 4.0,
"citation_count": 25005,
"brand_citation_count": 132,
"avg_sentiment": 0,
"avg_volume": 5190
}
]
},
"generated_at": "2026-11-09T05:50:44.151Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all"
}
{
"detail": "Invalid or revoked API key"
}
{
"detail": "API key not authorized for this domain."
}
{
"detail": "Domain not found"
}
{
"detail": "Too many requests. Please try again later."
}
This endpoint returns one scorecard for each topic of a domain. A scorecard adds up the metrics of all the prompts in the topic for the window.
Use this endpoint to find the topics where your brand is strong or weak. To compare groups of prompts by tag, use GET /api/v1/tag-metrics. To see each prompt, use GET /api/v1/prompt-metrics.
The domain_id parameter is required. To get domain IDs, use GET /api/v1/domains.
Authorizations
Your API key in the format Bearer ak_live_<your-key>. To make a key, go to Settings → Developers in the dashboard.
An optional UUID to find the request in logs. If you do not send one, the server makes one and returns it.
Query parameters
The UUID of the domain. To get it, use GET /api/v1/domains.
One AI channel by its generic name, or all. Examples: ChatGPT, Perplexity, Gemini, AI Overviews, AI Mode, Claude, Microsoft Copilot, Grok. The default is all.
The number of days to look back from today, from 1 to 365. The server uses the exact value. The default is 30.
The first day of a fixed window, in the format YYYY-MM-DD. Send it with end_date. Together, they replace days. The maximum range is 365 days.
The last day of a fixed window, in the format YYYY-MM-DD. The window includes this day. Send it with start_date.
If true, the server does not use the cache and calculates the result again. The default is false.
Response
The topic scorecards.
One scorecard for each topic of the domain.
The domain that you requested.
The window that you requested.
The model filter that you requested. If you did not send one, the value is all.
The ISO-8601 time when the server made or cached this response.
Response headers
| Header | Description |
|---|---|
X-Cache | HIT or MISS. If you send fresh=true, the value is REFRESH. |
X-Request-Id | The unique ID of the request. If you sent one, the server returns the same value. |
X-RateLimit-Limit | The maximum number of requests each minute for this key. |
X-RateLimit-Remaining | The number of requests that remain in the current minute. |
X-RateLimit-Reset | The Unix time in seconds when the window starts again. |
Caching
The server keeps each response in the cache for 1 hour. The cache key includes the domain, model and the dates of the window. A new topic shows after the cache expires. To get it at once, send fresh=true.
Errors
A date is not in the format YYYY-MM-DD, start_date is after end_date, or the range is longer than 365 days.
The API key is missing, not correct, or revoked.
API access is off for the team, or the domain is in a team that your key cannot access.
The domain_id is not valid, does not exist, or is not in your team.
domain_id is missing, or days is out of range.
You sent too many requests. Read the Retry-After header to know how long to wait.
Empty result
If the domain has no topics, the server returns 200 with an empty list:
{
"data": { "items": [] },
"generated_at": "2026-11-09T05:50:44.151Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all"
}