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
default 10
Rows per page. A value over the maximum reads as the maximum and sets filters_applied.limit_clamped. Allowed: 1–50.
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 `returned_count`. Allowed: 0 or more.

Example request

# $BRAND_PROMPT_ID — take one from listQueries.
curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
  "https://api.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:pNyl51MRfDXTGNpGSGObq_I3JkpWzDiIPFU8ItHOXPs",
    "limit": 10,
    "offset": 0
  },
  "has_more": false,
  "items": [
    {
      "completed_at": "2026-11-18T08:49:45.545350+00:00",
      "covers_all_providers": false,
      "error_code": null,
      "providers_scope": [
        "openai"
      ],
      "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-11-18T08:49:45.545576+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. providers_scope lists the AI platforms each run's advice covers (empty with covers_all_providers true means every platform); name them when you relay advice that covers only some.
400
Validation error — check the message in `error.message`.
401
Unauthorized — missing, invalid or revoked bearer token.
403
Forbidden — the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit.
404
Not found — the brand, prompt or resource does not exist.
405
Method not allowed.
429
Too many requests — over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.
500
Internal error — logged; retry is safe for reads.