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.