GET /v1/runs/:id

The record of any call by its call_id: status, class and cost. For a slow job it is the poll that settles it, with the 202 contract and intervals.

GET https://api.parel.si/v1/runs/:id

Scope read. Free. :id is the call_id from a run response (or the X-Call-Id header). Only calls belonging to your team are visible; any other id is not_found (404).

curl https://api.parel.si/v1/runs/ff83d554-fb75-4cf9-896a-bf53f91ea587 \
  -H "Authorization: Bearer $PAREL_KEY"

Response for a finished call

FieldTypeDescription
oktrueThe lookup succeeded, whatever the call's outcome
call_id, toolstring
classstringok, ok_free, replay, vendor_error, upstream_error or rejected
cost_paiseintegerWhat the call cost; 0 for every class but ok
errorstring or nullThe error code when there was one; no_result on an ok_free call that found nothing
latency_msintegerHow long the call took
created_at, finished_atstringISO 8601, UTC
notestring"This call was free." on every class but ok

The record does not include data: a finished call's answer is returned once, by the run itself, or by replay within 24 hours of a call made with an idempotency_key. Captured from staging, the failed call shown on the run page:

{
  "ok": true,
  "call_id": "ff83d554-fb75-4cf9-896a-bf53f91ea587",
  "tool": "search_web",
  "class": "upstream_error",
  "cost_paise": 0,
  "error": "upstream_error",
  "latency_ms": 228,
  "created_at": "2026-10-27T20:36:20.988Z",
  "finished_at": "2026-10-27T20:36:21.744Z",
  "note": "This call was free."
}

An id that is not yours (HTTP 404):

{
  "ok": false,
  "error": "not_found",
  "request_id": "409259c7-9212-45a1-91bd-aead29e1a38f"
}

Polling a slow job

When POST /v1/run answered 202, this endpoint is how the job is finished. Each read polls the source at most once per interval; reading more often just returns the last known state.

ResponseStatusBodyHeaders
Still running202ok: true, call_id, tool, class: "running", status (the source's own progress word), poll_after_seconds, cost_paise: 0Retry-After
Finished200ok: true, call_id, tool, class: "ok", cost_paise (the real cost, settled against the hold), balance_paise, data (the output and, when present, its sources; never the source's internal trace)X-Cost-Paise, X-Balance-Paise
Failed upstream422ok: false, call_id, tool, class: "vendor_error", error, charged_paise: 0, message

Rules of the contract:

  • Intervals. poll_after_seconds is the source's own interval (20 seconds when it names none). Polling sooner is harmless and returns the same state; the Retry-After header repeats the number.
  • The reserve. The hold placed at the start (reserved_paise on the 202) stays open while the job runs and is extended to 24 hours. The final charge is settled against it: the real cost is charged and the rest released. A job that fails is ₹0.
  • One delivery of data. The poll that sees the job finish returns data; later reads return the finished record without it. Keep what you receive.
  • A lost poll (a 5xx or timeout from the source while checking) does not fail the job; the next read tries again, with at least 30 seconds before it.
  • Abandoned jobs. A hold still open after 24 hours is expired by housekeeping and released; nothing is charged.

Over MCP the same read is get_run. The full picture, with what an agent should do at each step, is on Slow jobs. None of today's 268 tools is a slow job.

This page as Markdown: /docs/api/runs.md. Something wrong or missing: hello@parel.si.