> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/api/runs

# 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.

```text
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`](https://parel.si/docs/errors.md#not_found) (404).

```bash
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](https://parel.si/docs/api/run.md#errors):

```json
{
  "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):

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

## Polling a slow job

When [`POST /v1/run`](https://parel.si/docs/api/run.md#running) 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_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](https://parel.si/docs/slow-jobs.md). None of today's 268 tools is a slow job.
