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. - Cost
- Free. How cost is counted.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | A project in your workspace. |
week | date | No | Monday of the week as YYYY-MM-DD. Defaults to the last full UTC week. |
Errors
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_domain | domain is missing or not a valid domain. |
| 400 | invalid_week | week is not a Monday as YYYY-MM-DD. |
| 401 | unauthorized | The key is missing, malformed, unknown or revoked. |
| 404 | not_found | No project for that domain in the key’s workspace. |
| 429 | monthly_limit | The 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. |
| 429 | rate_limited | 120 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.