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. The public status vocabulary is three states: processing covers both ingestion/OCR (before a pipeline exists) and the compiled pipeline actually executing, ending 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.

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

Path parameters

id*uuidThe run_id returned by POST /v1/run.

curl

Response

Response fields

run_iduuidThe run request id.
spec_iduuidThe Spec being run.
statusstringprocessing, completed, or failed. processing covers both the pre-pipeline ingestion/OCR wait and the pipeline actually executing.
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.
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, or failed 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.

Related

Run a Spec
Webhook Events
Pipeline Progress