Citations Time Series

Daily count of citation entries on LLM responses that point to a tracked brand domain.

curl --request GET \
  --url 'https://api.aiclicks.io/api/v1/citations-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/citations-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']} citations")

const url = new URL("https://api.aiclicks.io/api/v1/citations-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} citations`);
}

{
  "data": {
    "items": [
      { "date": "2026-05-19", "value": 4 },
      { "date": "2026-05-20", "value": 7 },
      { "date": "2026-05-21", "value": 2 }
    ]
  },
  "domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
  "days": 30,
  "generated_at": "2026-06-17T10:00:11.218Z"
}

Citations is the raw count of citation entries in LLM responses that pointed to the brand domain each day, summed across every model channel.

value = sum over models of brand_citation_count

brand_citation_count for a (date, model) is the total number of citation array entries on responses that day whose URL host matches the tracked brand. The metric uses the same per-day, per-model SQL as the prompts page Mentions chart, so the values reconcile.

A response that cites three different brand URLs contributes three. A response with no brand citations contributes zero. For the share-of-citations percentage on the same data, use GET /citability-time-series.

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. Snapped to the nearest known bucket: 1, 7, 14, 30, 90, 180, 270, or 365 days.

Response

dataobject

Required

The list payload.

data.itemsarray

Required

One row per day in the window, oldest first. Days with no responses are omitted.

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

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 citations is calculated

For each (date, model) in the window:

Take every response that ran on a tracked prompt at that date and model.
For each response, walk its citations array and count entries whose URL host matches the brand domain.

Then sum those per-model counts within each date — that's the day's value. The unit is citation entries, not unique URLs: if a response's citations array contains the same brand URL twice, both entries count. The brand domain is resolved from the domain's configured website host with exact-host matching.

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 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"
}

Was this page helpful?