Heading API reference

A response is one collected AI answer with your property's mention verdict: whether the brand appeared, where, with what sentiment, and which URLs the platform cited. Verdict rows exist whether or not the brand was mentioned. Filter with mentioned to narrow to hits or misses.

List responses

GET /v1/responses

Returns responses for paid properties in the API key's scope. Ordered by date, newest first. Default range: the last 30 UTC days. List rows carry a plain-text excerpt; fetch the full markdown text from the detail endpoint.

Headers

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

Query parameters

Parameter	Type	Description
`propertyId`	string	Return responses for one property only.
`promptId`	string	Return responses for one prompt only.
`model`	string	Return responses for one AI platform only (e.g. `chatgpt`).
`mentioned`	boolean	`true` = only responses mentioning the brand; `false` = only misses.
`from`	string	Range start, UTC day (`yyyy-MM-dd`). Inclusive.
`to`	string	Range end, UTC day (`yyyy-MM-dd`). Inclusive.
`limit`	integer	Maximum results per page. Default: 100, max: 1000.
`offset`	integer	Rows to skip. Default: 0.

Example

curl "https://api.useheading.com/v1/responses?mentioned=true&model=chatgpt" \
  -H "Authorization: Bearer hdg_sk_live_abc123..."

Response: `200 OK`

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "promptId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "prompt": "What is the best SEO tool for enterprise?",
      "model": "chatgpt",
      "date": "2026-07-21",
      "mentioned": true,
      "matchedTerm": "Acme Corp",
      "position": 2,
      "sentiment": 0.6,
      "excerpt": "For enterprise SEO, the leading options are Conductor, Acme Corp, and BrightEdge. Conductor stands out for…",
      "sourceUrls": [
        "https://techcrunch.com/2026/05/12/enterprise-seo-tools",
        "https://reddit.com/r/seo/comments/enterprise_tools"
      ],
      "property": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "name": "Acme Corp"
      }
    }
  ],
  "total": 1
}

Response fields

Field	Type	Description
`id`	string	Response verdict UUID. Use with the detail endpoint.
`promptId`	string	Prompt UUID. Matches `id` on `/v1/prompts`.
`prompt`	string	The prompt text that produced this answer
`model`	string	AI platform identifier
`date`	string	UTC day the response was collected (`yyyy-MM-dd`)
`mentioned`	boolean	Whether the brand appeared in the answer
`matchedTerm`	string or null	The brand term that matched. Null when not mentioned.
`position`	number or null	Character position of the first mention. Null when not mentioned.
`sentiment`	number or null	Mention sentiment. Null when not mentioned.
`excerpt`	string	Plain-text excerpt of the answer (≤300 chars)
`sourceUrls`	string[]	URLs the platform cited or consulted
`property`	object	The property this verdict belongs to
`property.id`	string	Property UUID
`property.name`	string	Property display name

Get a response

GET /v1/responses/{id}

Returns one response with the full markdown answer text.

Example

curl https://api.useheading.com/v1/responses/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer hdg_sk_live_abc123..."

Response: `200 OK`

{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "promptId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "prompt": "What is the best SEO tool for enterprise?",
    "model": "chatgpt",
    "date": "2026-07-21",
    "mentioned": true,
    "matchedTerm": "Acme Corp",
    "position": 2,
    "sentiment": 0.6,
    "excerpt": "For enterprise SEO, the leading options are Conductor, Acme Corp, and BrightEdge. Conductor stands out for…",
    "text": "For enterprise SEO, the leading options are **Conductor**, **Acme Corp**, and **BrightEdge**.\n\n1. Conductor stands out for…",
    "sourceUrls": [
      "https://techcrunch.com/2026/05/12/enterprise-seo-tools"
    ],
    "property": {
      "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "name": "Acme Corp"
    }
  }
}

text: string. The complete answer as markdown. All other fields match the list row.

Error responses

Status	Code	When
`400`	`INVALID_PARAM`	Invalid query parameter
`401`	`MISSING_AUTH`	No Authorization header
`401`	`INVALID_AUTH`	Header is not `Bearer {key}`
`401`	`INVALID_KEY`	Invalid or revoked API key
`404`	`NOT_FOUND`	No response with this id in the key's scope
`429`	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded (100 req/min)
`500`	`INTERNAL_ERROR`	Server error

Responses

List responses

Headers

Query parameters

Example

Response: `200 OK`

Response fields

Get a response

Example

Response: `200 OK`

Error responses

On this page