talonic_get_run
Poll a Spec run started by talonic_run_spec: a normalized status, document-level progress, and — for pipeline runs — per-phase progress. Pass exactly one of run_id or pipeline_id — poll with pipeline_id when run_kind is pipeline, or with run_id when it is run.
When to use
- You just called
talonic_run_specand need to track progress. - You want to know when a run finished, or whether any documents errored.
- Poll every 5–10 seconds; stop as soon as
statusiscompletedorfailed.
When not to use
- Starting a run — use
talonic_run_spec. - Reading the structured rows once a run is complete — use
talonic_get_run_results.
Parameters
| Parameter | Type | Description |
|---|---|---|
| run_id | string | From a `run_kind: 'run'` envelope (`/v1/run`). Provide exactly one of `run_id` or `pipeline_id`. |
| pipeline_id | string | From a `run_kind: 'pipeline'` envelope (`/v1/pipelines`). Provide exactly one of `run_id` or `pipeline_id`. |
Response shape
Fields
| Parameter | Type | Description |
|---|---|---|
| status | string | `processing`, `completed` or `failed`, normalized across both backends. |
| raw_status | string|null | The backend's own status string, unnormalized. |
| progress.total_documents | number|null | Total documents in the run. |
| progress.completed_documents | number|null | Documents finished successfully. |
| progress.error_documents | number|null | Documents that errored. |
| progress.phases[] | array | Per-phase progress for pipeline runs — phase id, name, type, and completed/running/error counts. |
| documents[] | array | Per-document detail, when present. |
| error_message | string|null | Top-level error, when `status` is `failed`. |
Frequently asked questions
How long does a run take?+
Seconds per document for the extraction stage, plus whatever validation, resolution, assembly or delivery stages the Spec's rail contains; poll every 5–10 seconds and stop on completed or failed.