Skip to main content

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: while ingestion and OCR are still running the status is processing (no pipeline exists yet), it moves to running once the Spec's pipeline starts, and ends at completed or failed.

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.

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 webhooks, so poll or subscribe — whichever fits your integration.
GET/v1/run/:id

curl

Response

Response fields

run_iduuidThe run request id.
spec_iduuidThe Spec being run.
statusstringprocessing, running, completed, or failed.
pipeline_iduuid | nullThe compiled pipeline, once it exists.
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.
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
  },
  "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.

Related

Run a Spec
Webhook Events
Pipeline Progress