Sources Citation sources by domain and by URL
The sources API returns the websites AI platforms cite alongside your brand: aggregated by domain, and per URL for page-level detail.
Returns domain-level citation stats for paid properties in the API key's scope. Ordered by period start, newest first. Default range: the last 30 UTC days.
Header Value Required AuthorizationBearer hdg_sk_live_...Yes
Parameter Type Description propertyIdstring Return stats for one property only. domainstring Return stats for one source domain only. fromstring Range start, UTC day (yyyy-MM-dd). Inclusive. tostring Range end, UTC day (yyyy-MM-dd). Inclusive. limitinteger Maximum results per page. Default: 100, max: 1000. offsetinteger Rows to skip. Default: 0.
curl https://api.useheading.com/v1/sources \ -H "Authorization: Bearer hdg_sk_live_abc123..." { "data" : [ { "domain" : "techcrunch.com" , "usedPercent" : 45.2 , "avgCitations" : 3.1 , "sourceType" : "news" , "periodStart" : "2026-07-17" , "property" : { "id" : "f1e2d3c4-b5a6-7890-abcd-ef1234567890" , "name" : "Acme Corp" } } ], "total" : 1 } Field Type Description domainstring Source domain name usedPercentnumber Percentage of AI responses citing this source (0-100) avgCitationsnumber or null Average number of citations per response sourceTypestring or null Source category (e.g. news, blog, forum, docs) periodStartstring Period start, UTC day (yyyy-MM-dd) propertyobject The property this source data belongs to property.idstring Property UUID property.namestring Property display name
Returns per-URL stats: one row per property × URL × UTC day. Ordered by date, newest first. Default range: the last 30 UTC days.
Two metrics per row, each with its own denominator. Retrieval = the URL appeared in the platform's consulted/search results; citation = the URL was cited in the answer. A null rate means the metric is not available for the platforms in that cell. It is never an approximation.
Parameter Type Description propertyIdstring Return stats for one property only. domainstring Return URLs under one source domain only. modelstring Return stats for one AI platform only. Default: all platforms combined. fromstring Range start, UTC day (yyyy-MM-dd). Inclusive. tostring Range end, UTC day (yyyy-MM-dd). Inclusive. limitinteger Maximum results per page. Default: 100, max: 1000. offsetinteger Rows to skip. Default: 0.
curl "https://api.useheading.com/v1/sources/urls?domain=reddit.com" \ -H "Authorization: Bearer hdg_sk_live_abc123..." { "data" : [ { "url" : "https://reddit.com/r/seo/comments/enterprise_tools" , "domain" : "reddit.com" , "date" : "2026-07-21" , "model" : "_all" , "format" : "forum" , "communityPath" : "r/seo" , "retrievalRate" : 40.0 , "retrievalCount" : 2 , "retrievalResponses" : 5 , "citationRate" : null , "citationCount" : 0 , "citationResponses" : 0 , "property" : { "id" : "f1e2d3c4-b5a6-7890-abcd-ef1234567890" , "name" : "Acme Corp" } } ], "total" : 1 } Field Type Description urlstring Normalised full URL domainstring Source domain grouping key datestring UTC day (yyyy-MM-dd) modelstring Platform id, or _all for the all-platform rollup formatstring Page format (listicle, article, how_to, product, homepage, forum, video, other, …) communityPathstring or null Sub-community for UGC domains (e.g. r/seo) retrievalRatenumber or null % of measurable responses where the URL was consulted. Null = not available. retrievalCountnumber Responses where the URL appeared in the consulted set retrievalResponsesnumber Responses able to measure retrieval (denominator) citationRatenumber or null % of measurable responses citing the URL. Null = not available. citationCountnumber Responses citing the URL inline citationResponsesnumber Responses able to measure citations (denominator) propertyobject The property this row belongs to property.idstring Property UUID property.namestring Property display name
Status Code When 400INVALID_PARAMInvalid query parameter 401MISSING_AUTHNo Authorization header 401INVALID_AUTHHeader is not Bearer {key} 401INVALID_KEYInvalid or revoked API key 429RATE_LIMIT_EXCEEDEDRate limit exceeded (100 req/min) 500INTERNAL_ERRORServer error