Async research: submit, poll & idempotency

01Submit then poll

A research job has two calls. You submit with POST /v1/research/run and get a job handle back instantly; then you poll GET /v1/research/run/{id} until the job reaches a terminal state. Most jobs finish in 5–15 minutes and read up to ~40 sources, so the work happens off the request path — submit returns in moments, the report arrives on a later poll. Design for the job handle rather than an expected duration: a busy or source-heavy job can take longer.

Submit is the only billable event: $0.08 is charged once on a successful submit (statusCode < 400), regardless of depth. Polling is free — a poll writes no usage row — but it still requires the same bearer auth as every other call.

# 1) Submit the job — charged $0.08 once, returns a job handle.
curl -X POST https://api.stelq.com/v1/research/run \
  -H "Authorization: Bearer $STELQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Map AI-native search startups and their moats","depth":"deep","citations":true}'
# -> {"id":"rsch_8K2mQ9vX3pLw","status":"queued"}

# 2) Poll (free, auth still required) every 2–5s until status is terminal.
curl https://api.stelq.com/v1/research/run/rsch_8K2mQ9vX3pLw \
  -H "Authorization: Bearer $STELQ_KEY"

The documented lifecycle is queued → in_progress → completed, with terminal states completed, failed, or cancelled. On completed you read the result fields: result.outputText (render-ready prose), result.reportMarkdown (long-form), result.citations (source URLs), and result.dossier (the full structured retrieval packet). error is populated only on failed/cancelled.

{
  "id": "rsch_8K2mQ9vX3pLw",
  "status": "completed",
  "result": {
    "outputText": "AI-native search startups cluster around three moats…",
    "reportMarkdown": "# AI-native search startups\n\n## Moats\n…",
    "citations": [
      "https://eur-lex.europa.eu/eli/reg/2024/1689",
      "https://example.com/ai-search-landscape"
    ],
    "dossier": { "…": "full structured retrieval packet" }
  }
}

Polling is always the source of truth. You can optionally pass a webhook on submit to be notified on completion and skip polling, but a webhook is an optimization on top of polling, never a replacement. See Webhooks.

02Idempotency on submit

Submit is the one billed call that creates a side effect (an upstream job) and charges on success, so a naive client or agent retry could otherwise create two jobs and two $0.08 charges. To prevent that, the gateway dedupes at the submit boundary on an idempotency key, claimed before the upstream job is created — so a duplicate never makes a second job or a second charge.

There are two windows. Send a client Idempotency-Key (trimmed, max 200 chars) and that key dedupes for 24 hours. Send no header and the gateway derives a content-hash key from your API key id plus the request body and dedupes for exactly 90 seconds — enough to absorb naive submit retries without swallowing a deliberate re-run.

# Same key on every retry of THIS submit -> at most one job, one charge for 24h.
curl -X POST https://api.stelq.com/v1/research/run \
  -H "Authorization: Bearer $STELQ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-2026-06-16-moats-001" \
  -d '{"query":"Map AI-native search startups and their moats","depth":"deep"}'

The claim is atomic — a UNIQUE (api_key_id, idem_key) constraint means exactly one caller wins the claim and everyone else inspects the existing row. That yields three replay outcomes for a duplicate submit:

On a completed replay the gateway returns the original stored job handle and the Idempotent-Replay: true header, with no upstream call and no charge. A genuine in-flight duplicate gets 409 Retry-After: 2 — retry shortly. If the claim store can't be reached, submit fails closed with 503 Retry-After: 2 rather than risk charging a paid, side-effecting call twice.

03Related