Browse the documentation
Get Brand Visibility
How often the brand appears in AI answers, plus prominence score, average rank and sentiment. Group overall, by day, by platform or by tag.
GET
/visibility
Query parameters
| Name | Type | Description |
|---|---|---|
| brand required | string | Tracked brand name, exactly as returned by listTrackedBrands. |
| group_by |
string
default overall |
Grouping granularity.
One of: overall
day
provider
query_tag
|
| start_date | string | ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400. |
| end_date | string | ISO end date (YYYY-MM-DD). Defaults to today. |
| 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
|
Example request
curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
"https://api.mentionbird.ai/api/v1/visibility?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-11-18",
"start": "2026-10-20"
},
"filters_applied": {
"brand": "Acme",
"brand_prompt_id": null,
"end_date": "2026-11-18",
"group_by": "overall",
"llm_provider": null,
"query_tag": null,
"start_date": "2026-10-20"
},
"metrics": {
"avg_rank": 1.0,
"mention_runs": 1,
"net_sentiment": 100.0,
"prominence_pct": 100.0,
"sentiment_coverage_pct": 100.0,
"total_runs": 1,
"visibility_pct": 100.0
}
}
Responses
- 200
- Visibility metrics. 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 — 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.