Skip to main content

Get Run

Poll a processing run by ID with GET /v1/runs/:id to read its status, step progress, and, once complete, its markdown and structured extraction result.

The Get Run endpoint, GET /v1/runs/:id, retrieves a processing run by its ID to read its status and, once complete, its structured result. This is the polling target for the poll_url returned by POST /v1/process, for callers that prefer polling over the process.completed webhook.

While a run is in flight, status reports its progress and current_step names the step being executed. On completion the response carries the OCR-converted markdown, the structured_data extraction results, and any reconciliation output. On failure, the error object reports the failing step, an error code, and a message.

GET/v1/runs/:id

Path parameters

id*stringThe run UUID.

curl

curl -s https://api.talonic.com/v1/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

run_idstringThe run UUID.
statusstringRun status: pending, running, step_extract, step_structure, step_reconcile, completed, failed.
config_idstringThe processing configuration the run used.
batch_idstringThe batch identifier, when one was provided at submission.
created_atstringISO 8601 submission timestamp.
started_atstringISO 8601 timestamp when processing began.
completed_atstringISO 8601 timestamp when processing finished.
duration_msintegerTotal processing time in milliseconds.
current_stepstringThe step currently executing, while the run is in flight.
markdownstringOCR-converted markdown (present on completion).
structured_dataobjectStructured extraction results (present on completion).
reconciliationobjectReconciliation results (present on completion).
errorobjectOn failure: step, error_code, and message describing what went wrong.
Poll until status reaches completed or failed. The intermediate step statuses (step_extract, step_structure, step_reconcile) let you report pipeline progress to your users.

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundNo run with this ID exists for your organization.

Frequently asked questions

Should I poll or use the webhook?+
Either. The process.completed webhook pushes results; polling GET /v1/runs/:id pulls them. Webhooks are preferred for scale; polling is simpler for one-off scripts.
What statuses can a processing run have?+
A run moves through pending and running, then the step statuses step_extract, step_structure, and step_reconcile, and ends at completed or failed. Poll until you see one of the two terminal statuses.
When are markdown and structured_data populated?+
Only once the run reaches completed. Until then the response carries status and timing fields; on failure an error object reports the failing step, an error code, and a message instead.

Related

Submit for Processing
List Configs
Webhook Events