Competitors View tracked competitors across AI responses
The competitors API returns brands you're tracking alongside your own in AI search responses. Competitors belong to the team; team-wide competitors apply to every property, pinned competitors to one.
Returns competitors visible to the API key: team-wide competitors plus those pinned to paid properties in scope. Ordered by creation date, newest first. A key with no paid property in scope returns an empty list.
Header Value Required AuthorizationBearer hdg_sk_live_...Yes
Parameter Type Description propertyIdstring Return team-wide competitors plus those pinned to this property. limitinteger Maximum results per page. Default: 100, max: 1000. offsetinteger Rows to skip. Default: 0.
curl https://api.useheading.com/v1/competitors \ -H "Authorization: Bearer hdg_sk_live_abc123..." { "data" : [ { "id" : "d4e5f6a7-b8c9-0123-cdef-123456789012" , "displayName" : "BrightEdge" , "trackedName" : "BrightEdge" , "domains" : [ "brightedge.com" ], "propertyId" : null , "createdAt" : "2026-04-02T00:00:00.000Z" , "updatedAt" : "2026-06-30T00:00:00.000Z" } ], "total" : 1 } Field Type Description idstring Competitor UUID displayNamestring Display name trackedNamestring Name matched in AI responses domainsstring[] Competitor domains propertyIdstring or null Pinned property UUID. Null = team-wide. createdAtstring ISO 8601 creation timestamp updatedAtstring ISO 8601 last-update timestamp
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