Skip to content
MentionBird.ai
Browse the documentation

Get Ranking Advice for a Prompt

Completed ranking-advice runs for ONE prompt — what to change to rank better. Read-only: this never starts a new run. Requires brand_prompt_id from listQueries.

GET /prompts/ranking-advice

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.
limit integer Max runs to return.
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

# $BRAND_PROMPT_ID — take one from listQueries.
curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
  "https://app.mentionbird.ai/api/v1/prompts/ranking-advice?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",
    "limit": 10,
    "offset": 0
  },
  "has_more": false,
  "items": [
    {
      "completed_at": "2026-09-24T13:48:51.018699+00:00",
      "error_code": null,
      "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 prompt.
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.