DataForAEOby Advance Labs
Docs menu

GET · API key · Free

Citation index

Which domains AI answers cite for a topic, as shares across workspaces. Published only when at least 5 workspaces have matching prompts (privacy floor); otherwise insufficient_sample.

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

Parameters

NameTypeRequiredDescription
topicstringYesExact prompt match after lowercase and collapsed whitespace. Not embeddings.

Errors

HTTPcodeMeaning
400invalid_topictopic is missing or empty after trim.
400insufficient_sampleFewer than 5 workspaces have a matching prompt. The error carries sample_size; no domain list is returned.
401unauthorizedThe key is missing, malformed, unknown or revoked.
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.
  • Topic matching is exact after normalize (lowercase, collapse spaces). Prompt text never appears in the response.
  • rank_distribution counts how often the host appears at each 1-based position in an answer sources list.

Returns: Citation index.

Request
curl 'https://dataforaeo.dev/api/v1/citations?topic=best%20crm' \
  -H "Authorization: Bearer $DFA_KEY"
Response (trimmed, illustrative values)
{ "ok": true, "cost": { "checks": 0 }, "result": {
  "topic": "best crm", "sample_size": 12,
  "domains": [ { "domain": "g2.com", "share": 0.22, "citations": 31,
    "rank_distribution": { "1": 18, "2": 9, "3": 4 } } ] } }