Skip to content
MentionBird.ai
Browse the documentation

List Prompts by Visibility

Prompts ordered by visibility: ascending finds the gaps where the brand loses, descending finds the wins.

GET /prompts/by-visibility

Query parameters

Name Type Description
brand required string Tracked brand name, exactly as returned by listTrackedBrands.
order string
default asc 		Sort direction.
One of: asc desc
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.
query_tag string Filter to one tag slug.
llm_provider string Filter to one AI platform.
One of: openai claude gemini perplexity grok
country string ISO alpha-2 country code; 'ZZ' means Global.
min_search_volume integer Minimum volume bucket (1-10).
max_difficulty integer Maximum difficulty bucket (1-10).
search string Substring match on the prompt text.
limit integer
default 50 		Max rows (default 50, 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/prompts/by-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",
    "country": null,
    "end_date": "2026-09-24",
    "limit": 50,
    "llm_provider": null,
    "max_difficulty": null,
    "min_search_volume": null,
    "offset": 0,
    "order": "asc",
    "query_tag": null,
    "search": null,
    "start_date": "2026-08-26"
  },
  "has_more": false,
  "items": [
    {
      "any_brand_mention_rate_pct": 100.0,
      "any_brand_mention_runs": 1,
      "any_sources_rate_pct": 100.0,
      "any_sources_runs": 1,
      "avg_rank": 1.0,
      "brand_prompt_id": "bp:1:9Dv6siNdyM4t6TVuNmGTtlq8i258Tlktz9g8HkjWJtM",
      "country": "ZZ",
      "difficulty_bucket": 4,
      "mention_runs": 1,
      "net_sentiment": 100.0,
      "prominence_pct": 100.0,
      "prompt_text_preview": "best crm",
      "search_volume_bucket": 7,
      "sentiment_coverage_pct": 100.0,
      "tags": [
        "comparison"
      ],
      "total_runs": 1,
      "visibility_pct": 100.0
    }
  ],
  "returned_count": 1,
  "total_count": 1
}

Responses

200
Prompts ordered by visibility, each with its own net_sentiment so you can find the prompts the AIs talk about the brand badly in, not just the ones they omit it from. 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.