Citability Time Series
Daily share-of-citations percentage for a tracked domain across LLM responses.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/citability-time-series?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/citability-time-series",
params={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
for row in resp.json()["data"]["items"]:
print(f"{row['date']}: {row['value']}%")
const url = new URL("https://api.aiclicks.io/api/v1/citability-time-series");
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();
for (const row of data.items) {
console.log(`${row.date}: ${row.value}%`);
}
{
"data": {
"items": [
{ "date": "2026-05-19", "value": 15.0 },
{ "date": "2026-05-20", "value": 12.4 },
{ "date": "2026-05-21", "value": 8.7 },
{ "date": "2026-05-22", "value": 0 }
]
},
"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." }
Citability is your domain's slice of all citations made by LLM responses on a given day. Formally:
value = brand_citation_count / total_citation_count * 100
brand_citation_count is the number of citation entries on responses that day where the URL host matches your tracked brand domain. total_citation_count is the number of citation entries across every host on those same responses. The series rolls up every model channel — sum brand and total citations across models, then divide.
A day where every cited URL is on the brand returns 100. A day with zero citations returns value: 0. The math is identical to the Mentions chart's citability_percentage on the prompts page — values reconcile between the API and what you see in-product.
domain_id is a required query parameter. Use GET /api/v1/domains 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 GET /api/v1/domains. Omitting this returns 400.
Look-back window, 1–365. Defaults to 30. Snapped to the nearest known bucket: 1, 7, 14, 30, 90, 180, 270, or 365 days.
Response
The list payload.
One row per day in the window, oldest first.
Calendar date in YYYY-MM-DD (UTC).
Citability percentage, 0–100. brand_citation_count / total_citation_count * 100.
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 1 hour per (domain_id, days). Newly completed analyses appear after the TTL expires.
How citability is calculated
For each day in the window:
- Read every response that ran on a tracked prompt that day.
- For each response, count its citation entries — the numerator is those whose URL host matches the brand domain; the denominator is the full count regardless of host.
- Sum numerator and denominator across every model channel for the date.
- Divide, multiply by 100.
The brand domain is resolved from the domain's configured website host. Matching is exact host — subdomains and unrelated TLDs do not count toward the numerator but still contribute to the denominator if cited.
Citability counts citation entries, not unique URLs. If a response cites the same brand URL twice, both entries count toward brand_citation_count. This is the same counting unit used by the prompts page Mentions chart, so the numbers reconcile.
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 a successful 200 with an empty list:
{
"data": { "items": [] },
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"generated_at": "2026-06-17T10:00:11.218Z"
}