Skip to content
MentionBird.ai
Browse the documentation

Get Prompt Leaderboard

For ONE prompt: headline metrics plus every brand named on it, ranked. Requires brand_prompt_id from listQueries.

GET /prompts/leaderboard

Query parameters

Name Type Description
brand required string Tracked brand name, exactly as returned by listTrackedBrands.
brand_prompt_id required string Prompt ID token from listQueries.
window_days integer Trailing window in days (default 30, max 365).

Example request

# $BRAND_PROMPT_ID — take one from listQueries.
curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
  "https://app.mentionbird.ai/api/v1/prompts/leaderboard?brand=Acme&brand_prompt_id=$BRAND_PROMPT_ID"

Example response

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

{
  "filters_applied": {
    "brand": "Acme",
    "brand_prompt_id": "bp:1:9Dv6siNdyM4t6TVuNmGTtlq8i258Tlktz9g8HkjWJtM",
    "window_days": 30
  },
  "items": [
    {
      "avg_position": 1.0,
      "brand": "Acme",
      "is_your_brand": true,
      "mention_rate_pct": 100.0,
      "net_sentiment": 100.0,
      "rank": 1,
      "seen_on_providers": [
        "openai"
      ],
      "sentiment_coverage_pct": 100.0,
      "times_named": 1
    },
    {
      "avg_position": 2.0,
      "brand": "Globex",
      "is_your_brand": false,
      "mention_rate_pct": 100.0,
      "net_sentiment": 0.0,
      "rank": 2,
      "seen_on_providers": [
        "openai"
      ],
      "sentiment_coverage_pct": 100.0,
      "times_named": 1
    }
  ],
  "metrics": {
    "total_brand_mentions": 2,
    "total_entities": 2,
    "total_runs": 1,
    "window_days": 30,
    "your_avg_position": 1.0,
    "your_mention_rate_pct": 100.0,
    "your_rank": 1,
    "your_share_of_voice_pct": 50.0,
    "your_times_named": 1
  },
  "total_count": 2,
  "your_row": {
    "avg_position": 1.0,
    "brand": "Acme",
    "is_your_brand": true,
    "mention_rate_pct": 100.0,
    "net_sentiment": 100.0,
    "rank": 1,
    "seen_on_providers": [
      "openai"
    ],
    "sentiment_coverage_pct": 100.0,
    "times_named": 1
  }
}

Responses

200
Per-prompt brand leaderboard.
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.