---
title: "Poll a /v1/run request"
method: GET
path: "/v1/run/{id}"
tags: ["Run"]
---

# Poll a /v1/run request

`GET /v1/run/{id}`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/run/{id}`
- Auth: HTTP bearer

Row status, folded with the compiled pipeline's live progress once one exists (`pipeline_id` set). `status` is `processing` (in flight), `completed`, `failed`, or `cancelled` (the run, or the pipeline behind it, was stopped through `POST /v1/run/{id}/cancel`) — the same vocabulary `POST /v1/run` returns. A non-null `pipeline_id` plus the `progress` object indicate the pipeline has started. `documents` (when present) echoes each input's resolved document plus a per-entry live `status` — omitted entirely for runs submitted before this field shipped. Requires read scope.

## Path parameters

- `id` string, uuid, required

## Response `200`

Run request status.

- object
  - `run_id` string, uuid
  - `spec_id` string, uuid
  - `status` 'processing' | 'completed' | 'failed' | 'cancelled'
  - `pipeline_id` string, uuid, nullable
  - `pipeline_mode` 'new' | 'append': The EFFECTIVE mode this request resolved to (present only when recorded — omitted for legacy requests). Under `append` the pipeline is shared across requests, and `status`/`progress` are scoped to THIS request's own documents (the same all-terminal fold the per-request webhook fires on), not the whole pipeline.
  - `input_count` integer
  - `error_message` string, nullable
  - `metadata` object, nullable: The validated flat metadata object supplied on POST /v1/run, echoed back here.
  - `batch_id` string, nullable: The caller grouping key supplied on POST /v1/run, echoed back here.
  - `dispatch` false: Present only when the request sent `dispatch=false`.
  - `bindings` object: The per-node overrides supplied on POST /v1/run (`null` = that node skipped), echoed back here; present only when sent.
  - `dispatch_skipped` boolean: Present only when the request carried delivery controls: true when they suppress at least one Dispatch node (`dispatch=false` or any null `bindings` value). Derived from the stored controls; what actually happened per node is on GET /v1/pipelines/{id}/dispatches (status `skipped`).
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `progress` object, nullable: Present once the pipeline has started.
    - `total_documents` integer
    - `completed_documents` integer
    - `error_documents` integer
  - `documents` object[], nullable: Same items as POST /v1/run's response, each with an added per-entry status folded from the compiled pipeline's live per-document state (falls back to the run's own status when no pipeline is running yet, or the per-document fold could not be read). OPTIONAL — omitted entirely for runs submitted before this field shipped.
    - `document_id` string, uuid, required
    - `filename` string, nullable, required
    - `size_bytes` integer, nullable, required
    - `source` 'file' | 'file_url', required
    - `deduplicated` boolean, required
    - `existing_document_id` string, uuid: Present only when deduplicated is true — the canonical, i.e. the first upload of these bytes (equals duplicate_of.id when that is present).
    - `duplicate_of` object: Present on a duplicate occurrence — the first upload of these bytes, whose file bytes and OCR this occurrence reuses.
      - `id` string, uuid, required
      - `filename` string, nullable, required
    - `linked_document_id` string, uuid: Present only when deduplicated is true — the link row minted for this input (see POST /v1/run's documents[].linked_document_id).
    - `metadata` object: This input's EFFECTIVE per-request metadata, echoed from submit time (see POST /v1/run's documents[].metadata). Present only when set.
    - `status` 'processing' | 'completed' | 'failed' | 'cancelled', required

## Other responses

- `404`: Run request not found.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)