Skip to content
MentionBird.ai
Browse the documentation

List Sample AI Answers

Recent AI answers for the brand's prompts, each with a short preview of the answer. To read one answer in full, take its run_id from this list and call getQueryRun.

GET /query-runs

Query parameters

Name Type Description
brand required string Tracked brand name, exactly as returned by listTrackedBrands.
brand_prompt_id string Limit to one prompt — token from listQueries.
mentioned boolean true = only answers naming the brand; false = only answers that omit it; omit for both.
llm_provider string Filter to one AI platform.
One of: openai claude gemini perplexity grok
start_date string ISO start date (YYYY-MM-DD). Defaults to 30 days ago.
end_date string ISO end date (YYYY-MM-DD). Defaults to today.
limit integer
default 5 		Max rows (default 5, max 100).
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

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

Example response

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

{
  "date_range": {
    "days": 30,
    "end": "2026-09-24",
    "start": "2026-08-26"
  },
  "filters_applied": {
    "brand": "Acme",
    "brand_prompt_id": null,
    "end_date": "2026-09-24",
    "limit": 5,
    "llm_provider": null,
    "mentioned": null,
    "offset": 0,
    "start_date": "2026-08-26"
  },
  "has_more": false,
  "items": [
    {
      "brand_prompt_id": "bp:1:9Dv6siNdyM4t6TVuNmGTtlq8i258Tlktz9g8HkjWJtM",
      "citation_count": 2,
      "mention_rank": 1,
      "mention_sentiment": "positive",
      "prompt_text_preview": "best crm",
      "provider": "openai",
      "provider_display": "ChatGPT",
      "raw_response_excerpt": "Acme is the strongest option here. Acme is the strongest option here. Acme is the strongest option here. Acme is the strongest option here. Acme is the strongest option here. Acme is the strongest option here. Acme is the strongest option here. Acme is the strongest option here. Acme is the stronges…",
      "run_at": "2026-09-24T13:48:50.957069+00:00",
      "run_id": "qr:1:tLpe9gGs-dhlkL0FXP3-aghJtMofAUzYwvYu9byVFUk",
      "was_mentioned": true,
      "web_search_query_count": 1
    }
  ],
  "returned_count": 1,
  "total_count": 1
}

Responses

200
Sample AI answers, each with a ~300 character preview and a run_id. web_search_query_count is how many web searches the AI ran before answering: 0 means it answered without searching; null means the number is not recorded - Perplexity never exposes its searches, and runs from before we started recording them have no count. The search terms themselves are on getQueryRun. mention_sentiment is how that answer framed the brand - positive, neutral or negative. It is null when the answer never named the brand, and 'unknown' when it did but the run predates sentiment tracking; those are different facts, so do not read either as neutral.
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.