DataForAEOby Advance Labs
Docs menu

GET · API key · Free

AI referrals

Weekly AI-referral sessions (ChatGPT, Perplexity, Gemini, Copilot, Claude) for one of your sites from GA4, plus click-through against collector user fetches. Soft-fails with available:false while Google OAuth or the referrals schema is pending.

Endpoint
GET https://dataforaeo.dev/api/v1/referrals
Authentication
API key, sent as Authorization: Bearer dfa_live_…. How keys work.

Parameters

NameTypeRequiredDescription
domainstringYesA project in your workspace.
weekdateNoMonday of the week as YYYY-MM-DD. Defaults to the last full UTC week.

Errors

HTTPcodeMeaning
400invalid_domaindomain is missing or not a valid domain.
400invalid_weekweek is not a Monday as YYYY-MM-DD.
401unauthorizedThe key is missing, malformed, unknown or revoked.
404not_foundNo project for that domain in the key’s workspace.
429monthly_limitThe workspace used its API requests for the month. The allowance depends on the plan (see requests in /me); it resets on the 1st, UTC. The body carries an upgrade hint.
429rate_limited120 calls a minute per key. Wait for retry-after.

Every error code and the response envelope

Notes

  • No CORS on keyed endpoints: call it from a server.
  • When GA4 is not connected, the week was never pulled, or schema-app-referrals.sql is unapplied, the body is ok with available:false and a message (not a hard error).
  • click_through is D ÷ C for that Monday..Sunday week; null when there are no user fetches to divide by.

Returns: AI referrals.

Request
curl 'https://dataforaeo.dev/api/v1/referrals?domain=example.com' \
  -H "Authorization: Bearer $DFA_KEY"
Response (trimmed, illustrative values)
{ "ok": true, "cost": { "checks": 0 }, "result": {
  "available": true, "domain": "example.com", "week": "2026-11-10",
  "sessions": 12, "by_source": { "chatgpt": 8, "perplexity": 4 },
  "user_fetches": 100, "click_through": 0.12 } }