Heading API Reference

The visibility API returns per-date, per-model records showing how visible your brand is across AI search platforms.

List Visibility Data

GET /v1/visibility

Returns visibility records for active prompts scoped to the API key's allowed properties. Each record represents one model's visibility score for one day. Ordered by date, newest first.

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

Headers

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

Example

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

Response — `200 OK`

{
  "data": [
    {
      "date": "2026-03-20",
      "model": "chatgpt",
      "visibilityPct": 78.4,
      "mentionCount": 12,
      "avgPosition": 2.3,
      "avgSentiment": 0.85,
      "property": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "name": "Acme Corp"
      }
    },
    {
      "date": "2026-03-20",
      "model": "perplexity",
      "visibilityPct": 65.2,
      "mentionCount": 8,
      "avgPosition": 3.1,
      "avgSentiment": 0.72,
      "property": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "name": "Acme Corp"
      }
    }
  ],
  "total": 2
}

Response fields

Field	Type	Description
`date`	string	Date in `YYYY-MM-DD` format
`model`	string	AI platform identifier (e.g. `chatgpt`, `perplexity`, `ai_overview`, `_all`)
`visibilityPct`	number	Visibility percentage (0-100)
`mentionCount`	number	Number of times the brand was mentioned
`avgPosition`	number or null	Average position in AI responses (lower is better)
`avgSentiment`	number or null	Average sentiment score (-1 to 1)
`property`	object	The property this visibility 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

Visibility