GA4 key events
GA4 key events (conversions) attributed to AI-referred traffic — total, per-LLM breakdown, and top events — plus the previous period's total.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/ga4/key-events?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/ga4/key-events",
params={"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3", "days": 30},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
data = resp.json()["data"]
ke, prev = data["key_events"], data["previous_key_events_total"]
print(f"conversions: {ke['total']} ({ke['total'] - prev:+d} vs prior period)")
for e in ke["top_events"]:
print(f" {e['count']:>5} {e['event_name']}")
const url = new URL("https://api.aiclicks.io/api/v1/ga4/key-events");
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.log(data.key_events.total, "vs", data.previous_key_events_total);
{
"data": {
"key_events": {
"total": 86,
"by_llm": {
"chatgpt": {
"total": 60,
"events": [
{ "event_name": "signup", "count": 48 },
{ "event_name": "purchase", "count": 12 }
]
},
"perplexity": {
"total": 26,
"events": [ { "event_name": "signup", "count": 26 } ]
}
},
"top_events": [
{ "event_name": "signup", "count": 74 },
{ "event_name": "purchase", "count": 12 }
]
},
"previous_key_events_total": 71
},
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"llm_source": null,
"generated_at": "2026-07-13T10: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": "Too many requests. Please try again later." }
The conversions — GA4 key events — driven by AI-referred traffic: the total over the window, a breakdown of which assistant drove them (by_llm), the most-triggered events overall (top_events), and the previous period's total for a delta. This is the bottom-of-funnel answer: did AI-referred visitors actually do the thing that matters (sign up, purchase, book a demo), and which assistant deserves the credit.
Which GA4 events count as "key events" is configured in the connected GA4 property, so the event names you see here mirror that setup.
domain_id is a required query parameter. Use GET /api/v1/domains to discover which domains the calling key can access. When the domain has no connected GA4 property (or no AI-referred key events in the window), the call returns 200 with total: 0, empty by_llm/top_events, and previous_key_events_total: 0.
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.
Trailing look-back window, 1–365. Defaults to 30. previous_key_events_total covers the window of equal length immediately before it.
Optional. Restrict to a single AI/LLM referral source — chatgpt, perplexity, claude, gemini, copilot, … With a filter set, total, by_llm, and top_events reflect only that source. Omit for all sources.
Response
The key-events payload.
The conversion rollup for AI-referred traffic.
Total key events for the immediately preceding window of equal length. 0 if there is no prior data.
Echo of the requested domain.
Echo of the requested window.
Echo of the requested llm_source filter, or null when unset.
ISO-8601 timestamp of when the server produced (or cached) this response.
Response headers
| Header | Description |
|---|---|
X-Cache | HIT or MISS. 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 the current minute. |
X-RateLimit-Reset | Unix epoch seconds when the window resets. |
Caching
Cached for a short window per (domain_id, days, llm_source). Freshly synced GA4 data appears after the TTL expires.
Empty result
{
"data": {
"key_events": { "total": 0, "by_llm": {}, "top_events": [] },
"previous_key_events_total": 0
},
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"llm_source": null,
"generated_at": "2026-07-13T10:00:11.218Z"
}