Heading API Reference

The sources API returns websites that AI platforms cite alongside your brand. Source stats are aggregated per period and show how frequently each domain is referenced.

List Sources

GET /v1/sources

Returns citation source statistics scoped to the API key's allowed properties. Ordered by period start date, newest first.

Keys with all properties access return sources across every property on the team
Scoped keys return only sources for their authorised properties

Headers

Header	Value	Required
`Authorization`	`Bearer hdg_sk_live_...`	Yes

Example

curl https://api.useheading.com/v1/sources \
  -H "Authorization: Bearer hdg_sk_live_abc123..."

Response — `200 OK`

{
  "data": [
    {
      "domain": "techcrunch.com",
      "usedPercent": 45.2,
      "avgCitations": 3.1,
      "sourceType": "news",
      "periodStart": "2026-03-17",
      "property": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "name": "Acme Corp"
      }
    },
    {
      "domain": "reddit.com",
      "usedPercent": 28.7,
      "avgCitations": 1.8,
      "sourceType": "forum",
      "periodStart": "2026-03-17",
      "property": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "name": "Acme Corp"
      }
    }
  ],
  "total": 2
}

Response fields

Field	Type	Description
`domain`	string	Source domain name
`usedPercent`	number	Percentage of AI responses citing this source (0-100)
`avgCitations`	number or null	Average number of citations per response
`sourceType`	string or null	Source category (e.g. `news`, `blog`, `forum`, `docs`)
`periodStart`	string	Period start date in `YYYY-MM-DD` format
`property`	object	The property this source data belongs to
`property.id`	string	Property UUID
`property.name`	string	Property display name

Error responses

Status	Code	When
`401`	`MISSING_AUTH`	No Authorization header
`401`	`INVALID_KEY`	Invalid or revoked API key
`429`	`rate_limit_exceeded`	Rate limit exceeded (100 req/min)
`500`	`INTERNAL_ERROR`	Server error

Sources