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.
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://app.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-09-24",
    "start": "2026-08-26"
  },
  "filters_applied": {
    "brand": "Acme",
    "brand_prompt_id": null,
    "end_date": "2026-09-24",
    "group_by": "overall",
    "llm_provider": null,
    "query_tag": null,
    "start_date": "2026-08-26"
  },
  "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 — 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.