Poll a Run
Poll a /v1/run request by id: run status folded with live pipeline progress, per-document completion counts, and the echoed batch_id and metadata tags.
The Poll a Run endpoint, GET /v1/run/:id, reads a /v1/run request by the run_id returned on submission. The response folds the request row together with the compiled pipeline's live progress. The public status vocabulary is four states: processing covers both ingestion/OCR (before a pipeline exists) and the compiled pipeline actually executing, ending at completed, failed, or cancelled (the run, or the pipeline behind it, was stopped through POST /v1/run/:id/cancel or POST /v1/pipelines/:id/cancel).
Once the pipeline exists, pipeline_id is set and a progress object reports per-document counts — how many documents finished, and how many errored. A run reports failed only when every document errored (no usable output); a run where some documents succeeded and some errored completes with the error count visible in progress.error_documents.
The response also echoes documents[] — the same array returned at submission, each entry augmented with a per-document status (processing, completed, or failed) so you can tell which specific inputs are still in flight without waiting for the whole run to finish. documents[] is omitted for runs submitted before this field existed.
Poll this endpoint, not the pipeline: the run request is the stable public handle, and its status is folded live at read time. The same terminal states also fire the run.completed / run.failed / run.cancelled webhooks, so poll or subscribe — whichever fits your integration. To stop a run, POST /v1/run/:id/cancel — it cancels the whole pipeline behind the request, including other requests appended to it.
GET
/v1/run/:idPath parameters
id*uuidThe run_id returned by POST /v1/run.
curl
curl -s https://api.talonic.com/v1/run/a8716d18-978d-4d19-8ca5-8b3784ca857c \
-H "Authorization: Bearer tlnc_your_api_key"Response
Response fields
run_iduuidThe run request id.
spec_iduuidThe Spec being run.
statusstringprocessing, completed, failed, or cancelled. processing covers both the pre-pipeline ingestion/OCR wait and the pipeline actually executing; cancelled means the run was stopped and finished documents keep their results.
pipeline_iduuid | nullThe compiled pipeline, once it exists.
pipeline_modestringPresent only when recorded: the effective mode the run resolved to (new or append). Under append the pipeline is shared across requests, and status/progress are scoped to THIS request's own documents.
input_countintegerTotal inputs accepted at submission.
batch_idstring | nullThe caller grouping key supplied on submission, echoed back.
metadataobject | nullThe validated flat metadata object supplied on submission, echoed back.
error_messagestring | nullPopulated when the run failed before a pipeline existed (e.g. every input failed OCR).
progressobject | nullPresent once the pipeline has started: total_documents, completed_documents, error_documents, and cancelled_documents after a cancel.
dispatchbooleanPresent (false) only when the request was submitted with dispatch=false.
bindingsobjectThe per-request binding overrides, echoed when the request sent delivery controls.
dispatch_skippedbooleanPresent when delivery controls were sent: true when they suppress at least one Dispatch node (dispatch=false or any null bindings value).
documents[]arrayThe submit-time documents[] array, each entry augmented with a per-document status. Omitted for runs submitted before this field existed.
documents[].statusstringprocessing, completed, failed, or cancelled for this specific document.
documents[].metadataobjectThis input's EFFECTIVE per-request metadata (call-level metadata merged with its file_metadata entry, per-file wins), echoed from submission. Present only when set.
created_atstringISO 8601 submission timestamp.
updated_atstringISO 8601 last-transition timestamp.
Response (completed)
{
"run_id": "a8716d18-978d-4d19-8ca5-8b3784ca857c",
"spec_id": "1fc7807e-e1aa-4504-b796-5709986e78ed",
"status": "completed",
"pipeline_id": "1a0c681d-ea20-4bb4-8892-01a6d7f834da",
"input_count": 1,
"batch_id": "ERP-2026-07-14-001",
"metadata": { "source_system": "sap", "priority": 1 },
"progress": {
"total_documents": 1,
"completed_documents": 1,
"error_documents": 0
},
"documents": [
{
"document_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"filename": "invoice-0847.pdf",
"size_bytes": 184320,
"source": "file",
"deduplicated": false,
"metadata": { "source_system": "sap", "priority": 1, "cost_center": "AP-14" },
"status": "completed"
}
],
"created_at": "2026-07-14T21:04:11.312Z",
"updated_at": "2026-07-14T21:06:48.977Z"
}Errors
Error responses
401unauthorizedMissing or invalid API key.
404not_foundNo run with this id exists for your organization.
Cancel a run
POST
/v1/run/:id/cancelResponses
200object{ run_id, pipeline_id, id, status, already, cancelled_at, documents { total, completed, cancelled, errored }, run_requests[], jobs }. already is true when the pipeline was already terminal (idempotent).
404not_foundNo run with this id exists for your organization.
409not_cancellable_yetThe run is still ingesting and no pipeline exists yet. Retry shortly.
Cancel a run
curl -s -X POST https://api.talonic.com/v1/run/a8716d18-978d-4d19-8ca5-8b3784ca857c/cancel \
-H "Authorization: Bearer $TALONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "wrong spec selected" }'Frequently asked questions
What do the four statuses mean?+
processing = the run is in flight — either ingestion/OCR before a pipeline exists, or the Spec's compiled pipeline actually executing (both fold to the same word); completed = the run finished with usable output; failed = no usable output (every document errored, or ingestion itself failed — see error_message); cancelled = the run or its pipeline was stopped, and documents that finished before the cancel keep their results.
Why does cancel return 409 not_cancellable_yet?+
The run is still ingesting and no pipeline exists yet, so there is nothing to stop. Retry the cancel shortly; once the pipeline exists the call succeeds, and it is idempotent on a run that is already terminal.
When does a run count as failed?+
Only when every document errored. A partially successful run — some documents completed, some errored — reports completed, with the error count in progress.error_documents, and the failing documents visible on the pipeline.
Where is the structured output?+
Delivered by the Spec's Dispatch nodes to the destinations their bindings name, which is the primary results-delivery path. To pull instead, poll GET /v1/run/:id/results, read the pipeline's data product via pipeline_id, or subscribe to run.completed and read its records[] array.
What does the per-document status in documents[] tell me?+
Whether that specific input has finished, independent of the overall run: processing, completed, or failed. This lets you show progress for individual uploads in a multi-file run instead of waiting for every document to settle. It is derived from live pipeline-document state, so it can complete before the top-level run status does.
What changes when pipeline_mode is append?+
The pipeline behind the run is shared by many requests, so the poll reports YOUR request: status folds over this request's own documents (completed once they are all terminal, failed only when they all errored), and progress counts them — not the whole shared pipeline. The run.completed webhook is scoped the same way and carries this run_id.