GET /v1/ask/{id}

Retrieve any of your prior /v1/ask responses by id. Used both to re-read historical synchronous calls and to poll for the result of a mode: "standard" async job.

Legacy endpoint. This documents an older surface kept for back-compat with existing integrations. New integrations should use /v1/check instead — see the quickstart for the modern API.

GET/v1/ask/{id}— Retrieve a prior /v1/ask response

Path parameters

Field	Type	Description
`id` required	`string`	The id returned by POST /v1/ask (same value as request_id and ask_id in the creation response). Must belong to the calling account.

Retention & availability

Responses are archived for 30 days from creation. A background prune job removes older rows, and the handler also enforces the window at read time — an id older than 30 days returns 410 expired.

For mode: "standard" requests, the job is enqueued on creation and typically completes within 15 minutes. Poll this endpoint until status becomes succeeded or failed. Webhook-delivered async calls (async: true) also write to the archive, so you can back-fill state via this endpoint even if your receiver missed the webhook.

Response

The shape depends on status. All states share request_id and id.

Field	Type	Description
`request_id`optional	`string`	This read request's id (for correlation with logs).
`id`optional	`string`	The archived ask id — echoes the path parameter.
`status`optional	`'queued' \| 'processing' \| 'succeeded' \| 'failed'`	Lifecycle state. queued/processing return HTTP 202; succeeded and failed return HTTP 200.

Top-level fields returned at all states

status: "succeeded"

The archived payload is spread into the top-level response. The fields match the full POST /v1/ask response: providers[], brand_mentions[], citations[], usage, cached, and cache_tier.

status: "failed"

Field	Type	Description
`error`optional	`{ code: string, message: string }`	Error detail captured when the job was processed. Defaults to { code: 'provider_error', message: 'Request failed.' } if no detail was recorded.

status: "queued" / "processing"

Only request_id, id, and status are returned with HTTP 202. Retry after a short delay.

Example: succeeded

json

{
  "request_id": "req_01H8X2Y3Z4ABC",
  "id": "ask_01H8X2Y3Z4PQR5STU6VW7XYZ8",
  "cached": false,
  "cache_tier": "miss",
  "providers": [
    {
      "provider": "openai",
      "model": "gpt-4o-2024-11-20",
      "content": "Supabase has emerged as a developer favorite…",
      "latency_ms": 1240,
      "tokens": { "input": 64, "output": 312 },
      "citations": [
        { "url": "https://supabase.com/pricing", "domain": "supabase.com", "title": "Pricing | Supabase" }
      ]
    }
  ],
  "brand_mentions": [
    { "brand": "Supabase", "provider": "openai", "rank": 0, "sentiment": "positive", "context": "Supabase has emerged…" }
  ],
  "citations": [
    { "url": "https://supabase.com/pricing", "domain": "supabase.com", "title": "Pricing | Supabase" }
  ],
  "usage": {
    "billable_units": 1,
    "latency_ms": 1240,
    "cost_cents": 4,
    "cost_breakdown": {
      "our_price_cents": 4,
      "upstream_cost_cents_estimate": 1,
      "margin_cents": 3,
      "by_provider": []
    }
  }
}

Example: queued (HTTP 202)

json

{
  "request_id": "req_01HREAD789",
  "id": "ask_01H8X2Y3Z4PQR5STU6VW7XYZ8",
  "status": "queued"
}

cURL

bash

curl https://api.mentionsapi.com/v1/ask/ask_01H8X2Y3Z4PQR5STU6VW7XYZ8 \
  -H "Authorization: Bearer $MENTIONSAPI_KEY"

TypeScript SDK

typescript

import { MentionsAPIClient } from "@mentionsapi/sdk";

const client = new MentionsAPIClient({ apiKey: process.env.MENTIONSAPI_KEY! });

// Fire a standard-mode (async, 30% cheaper) ask
const queued = await client.ask({
  prompt: "Best PostgreSQL hosting providers in 2026?",
  providers: ["openai", "anthropic", "perplexity"],
  mode: "standard",
});

// Poll until it completes
async function poll(id: string) {
  while (true) {
    const res = await client.askRetrieve(id);
    if (res.status === "succeeded" || res.status === undefined) return res;
    if (res.status === "failed") throw new Error(res.error?.message ?? "failed");
    await new Promise((r) => setTimeout(r, 5_000));
  }
}

const result = await poll(queued.ask_id ?? queued.id);
console.log(result.providers);

Python

python

import os
import time
import httpx

BASE = "https://api.mentionsapi.com"
headers = {"Authorization": f"Bearer {os.environ['MENTIONSAPI_KEY']}"}

def retrieve(ask_id: str):
    r = httpx.get(f"{BASE}/v1/ask/{ask_id}", headers=headers)
    r.raise_for_status()
    return r.json()

ask_id = "ask_01H8X2Y3Z4PQR5STU6VW7XYZ8"
while True:
    res = retrieve(ask_id)
    status = res.get("status", "succeeded")
    if status in ("succeeded", "failed"):
        print(res)
        break
    time.sleep(5)

Errors

Field	Type	Description
`invalid_request`optional	`400`	Missing or oversized id parameter (length > 256).
`invalid_api_key`optional	`401`	Bearer token missing, malformed, or revoked.
`not_found`optional	`404`	No /v1/ask response with that id exists for this account.
`expired`optional	`410`	The row is older than the 30-day retention window. The response includes retention_days: 30.
`internal_error`optional	`500`	The archive read failed. Retry, or contact support with the request_id from the response body.

See the full error reference for payload shape and retry guidance.

Response headers

Field	Type	Description
`X-RateLimit-Limit`optional	`number`	Your account's rate-limit ceiling for the current window.
`X-RateLimit-Remaining`optional	`number`	Calls remaining in the current window before 429s begin.
`Retry-After`optional	`number (seconds)`	Sent on 429 responses. Sleep at least this long before retrying.

The unique call identifier is returned in the JSON body as request_id. Use that value in support tickets.