Skip to content
MentionBird.ai
Browse the documentation

List Ranking Advice Runs

Ranking-advice runs across ALL of a brand's prompts. Use this to find which prompts already have advice before calling getRankingAdvice.

GET /ranking-advice

Query parameters

Name Type Description
brand required string Tracked brand name, exactly as returned by listTrackedBrands.
limit integer
default 20 		Max rows (default 20).
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`.
status string Lifecycle filter. Most callers want 'done'.
One of: done running pending error
search string Substring match on the prompt text. Not the generated summary.

Example request

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

Example response

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

{
  "filters_applied": {
    "brand": "Acme",
    "limit": 20,
    "offset": 0,
    "search": null,
    "status": null
  },
  "has_more": false,
  "items": [
    {
      "brand_prompt_id": "bp:1:9Dv6siNdyM4t6TVuNmGTtlq8i258Tlktz9g8HkjWJtM",
      "completed_at": "2026-09-24T13:48:51.018699+00:00",
      "country": "ZZ",
      "error_code": null,
      "prompt_text": "best crm",
      "recommendations": [
        {
          "action_type": "update_page",
          "est_difficulty": "low",
          "rationale": "G2 is the most-cited source on this prompt and its comparison table is a year old.",
          "supporting_evidence": [
            "https://www.g2.com/categories/crm"
          ],
          "topic": "Refresh the G2 category listing"
        }
      ],
      "run_id": 1,
      "started_at": "2026-09-24T13:48:51.018998+00:00",
      "status": "done",
      "summary": "Acme already ranks first here. Hold the position by keeping the G2 category page current.",
      "tool_call_count": 3
    }
  ],
  "offset": 0,
  "returned_count": 1,
  "total_count": 1
}

Responses

200
Ranking advice runs for the brand.
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.