Skip to content
MentionBird.ai
Browse the documentation

Get Share of Voice

The brands named most often across this brand's tracked prompts — who you are losing to, and by how much.

GET /brands/top-mentioned

Query parameters

Name Type Description
brand required string Tracked brand name, exactly as returned by listTrackedBrands.
start_date string ISO start date (YYYY-MM-DD). Defaults to 30 days ago.
end_date string ISO end date (YYYY-MM-DD). Defaults to today.
filter_by_brand string Only answers that also mention this brand.
exclude_brand string Only answers that do not mention this brand.
brand_prompt_id string Limit to one prompt — token from listQueries.
query_tag string Filter to one tag slug.
llm_provider string Filter to one AI platform.
One of: openai claude gemini perplexity grok
limit integer
default 20 		Max rows (default 20, max 100).
offset integer
default 0 		Rows to skip — the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `limit`.

Example request

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

Example response

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

{
  "date_range": {
    "days": 30,
    "end": "2026-09-24",
    "start": "2026-08-26"
  },
  "filters_applied": {
    "brand": "Acme",
    "brand_prompt_id": null,
    "end_date": "2026-09-24",
    "exclude_brand": null,
    "filter_by_brand": null,
    "limit": 20,
    "llm_provider": null,
    "offset": 0,
    "query_tag": null,
    "start_date": "2026-08-26"
  },
  "has_more": false,
  "items": [
    {
      "avg_rank": 1.0,
      "brand_name": "Acme",
      "domain": "acme.com",
      "is_tracked_competitor": false,
      "is_you": true,
      "mention_count": 1,
      "net_sentiment": 100.0,
      "sentiment_coverage_pct": 100.0,
      "share_pct": 100.0
    },
    {
      "avg_rank": 2.0,
      "brand_name": "Globex",
      "domain": "globex.com",
      "is_tracked_competitor": false,
      "is_you": false,
      "mention_count": 1,
      "net_sentiment": 0.0,
      "sentiment_coverage_pct": 100.0,
      "share_pct": 100.0
    }
  ],
  "returned_count": 2,
  "total_count": 2
}

Responses

200
Brands ranked by mentions, each with its own sentiment so the brand can be compared with its competitors on tone as well as share of voice. net_sentiment is -100..+100: how the AI platforms talk about the brand, not how often they name it. +100 = every labeled mention recommends it, -100 = every one criticizes it, 0 = balanced or uniformly neutral. It is computed over labeled mentions ONLY. sentiment_coverage_pct is what share of mentions carry a label; anything crawled before sentiment tracking began is unlabeled and counts toward neither side. Read the two together - net_sentiment 0 with coverage 0 means no data, not neutral, and must never be reported as neutral.
400
Validation error — check the message in `error.message`.
401
Unauthorized — missing, invalid or revoked bearer token.
403
Forbidden — plan lacks API access, or key is read-only.
404
Not found — the brand, prompt or resource does not exist.
405
Method not allowed.
500
Internal error — logged; retry is safe for reads.