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
| Field | Type | Description |
|---|---|---|
ok | true | The lookup succeeded, whatever the call's outcome |
call_id, tool | string | |
class | string | ok, ok_free, replay, vendor_error, upstream_error or rejected |
cost_paise | integer | What the call cost; 0 for every class but ok |
error | string or null | The error code when there was one; no_result on an ok_free call that found nothing |
latency_ms | integer | How long the call took |
created_at, finished_at | string | ISO 8601, UTC |
note | string | "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.
| Response | Status | Body | Headers |
|---|---|---|---|
| Still running | 202 | ok: true, call_id, tool, class: "running", status (the source's own progress word), poll_after_seconds, cost_paise: 0 | Retry-After |
| Finished | 200 | ok: 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 upstream | 422 | ok: false, call_id, tool, class: "vendor_error", error, charged_paise: 0, message |
Rules of the contract:
- Intervals.
poll_after_secondsis the source's own interval (20 seconds when it names none). Polling sooner is harmless and returns the same state; theRetry-Afterheader repeats the number. - The reserve. The hold placed at the start (
reserved_paiseon 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 returnsdata; 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.