Skip to content
MentionBird.ai
Browse the documentation

List Competitors

List the competitors tracked for a brand, with each one's domain. getTopMentionedBrands marks their rows is_tracked_competitor.

GET /brands/competitors

Query parameters

Name Type Description
brand required string Tracked brand name, exactly as returned by listTrackedBrands.

Example request

curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
  "https://api.mentionbird.ai/api/v1/brands/competitors?brand=Acme"

Example response

Recorded from a live call against a demo workspace, so the shape is exactly what the endpoint returns.

{
  "has_more": false,
  "items": [
    {
      "domain": "globex.com",
      "domains": [
        {
          "domain": "globex.com",
          "include_subdomains": true
        }
      ],
      "name": "Globex"
    }
  ],
  "returned_count": 1,
  "total_count": 1
}

Responses

200
Tracked competitors in name order. domains lists the domains this workspace declared for each, with include_subdomains; they are what the 'competitor:<name>' ownership label matches, and an empty list means none are declared. domain is the first declared domain, else the competitor's public domain, else null. A competitor gets a row in getTopMentionedBrands only when answers in the range named it, and not even then when every spelling of it falls inside the tracked brand's own spellings or an earlier-added competitor's: its mentions count under that row instead.
400
Validation error — check the message in `error.message`.
401
Unauthorized — missing, invalid or revoked bearer token.
403
Forbidden — the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit.
404
Not found — the brand, prompt or resource does not exist.
405
Method not allowed.
429
Too many requests — over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.
500
Internal error — logged; retry is safe for reads.