Skip to content
MentionBird.ai
Browse the documentation

Start Ranking Advice

Start a ranking-advice run for one prompt, spending credits: the price getAccount lists under agents.ranking_advice, charged when the run starts and refunded if it fails. The run takes 5-12 minutes, so this answers at once with run_id and status; read the advice with getRankingAdvice once status is done. A finished run whose sources haven't changed comes back free, as does a run already in progress, and an account that can't pay gets error_code insufficient_credits; none of these starts a run or charges anything. started is true only when this call started one, and credits is what it spends. Requires a write-enabled API key.

POST /ranking-advice/runs

Request body

Send as application/json. This endpoint needs a write-enabled API key.

Field Type Description
brand required string Tracked brand name.
brand_prompt_id required string Prompt ID token from listQueries.
providers array of string AI platforms to build the advice from, e.g. ['openai'] for ChatGPT only. Omit for every platform the prompt runs on; one it doesn't run on is a 400.

Example request

curl -X POST -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "brand": "Acme",
  "brand_prompt_id": "Acme"
}' \
  "https://api.mentionbird.ai/api/v1/ranking-advice/runs"

Responses

200
The run started, or the existing run returned.
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.