Skip to main content

Queue & List Runs

Queue a run of one document page with POST /v1/chart-to-data/runs and list runs without results by document, file hash or page, newest first, at most 200.

POST /v1/chart-to-data/runs queues a run of one page: the body names the document_id and the page_number. The route resolves the file hash, binds the latest stored inputs for that file page when there are any (input_id, otherwise null), stores a run in status queued, and returns it at once with 201. The worker binds inputs still missing when it executes the run: latest stored, else derived from the page, else the run fails with INPUTS_MISSING.

Queuing never opens the file, so problems that depend on the page itself surface as a failed run and not as an error here. A run fails with an error_code such as INPUTS_MISSING (no inputs stored and none could be derived), PAGE_OUT_OF_RANGE, SOURCE_CHANGED (the bytes read no longer hash to the run's hash), NOT_A_PDF or PDF_UNREADABLE, or an engine refusal such as WRONG_SOURCE_HASH, FRAME_OUTSIDE_SOURCE_PAGE or MISSING_METADATA. Only transient failures, such as an unreadable file, are retried, up to a configured number of attempts; engine refusals are deterministic and fail at once.

GET /v1/chart-to-data/runs lists runs without their results, newest first, at most 200. document_id narrows to one document; source_sha256 narrows to one file through any uploaded copy of it; page_number narrows to a page. The list is how a client finds the latest run of a page, and GET /v1/chart-to-data/runs/{id} returns the results. Every run carries the engine_version it was queued under and the input_id it is bound to.

POST/v1/chart-to-data/runs

Body fields

document_id*uuidThe document whose file is read.
page_number*integer1 or greater. Whether the page exists is known only when the run executes.
GET/v1/chart-to-data/runs

Query parameters

document_iduuidRuns of one document.
source_sha256stringRuns of one file through any uploaded copy of it, 64 lowercase hex characters.
page_numberinteger1 or greater.

Run fields (data[])

iduuidThe run.
customer_id, document_iduuidThe workspace and the document the run was queued through.
source_sha256, page_numberstring, integerThe file page the run reads.
input_iduuid | nullThe inputs version the run uses; null until bound.
engine_versionstringThe engine version the run was queued under.
statusstringqueued, running, done or failed.
attemptsintegerExecution attempts so far.
error_code, error_messagestring | nullThe engine's own code (such as WRONG_SOURCE_HASH or INPUTS_MISSING) or an app code, when failed.
created_by, created_at, started_at, finished_atstring | nullWho queued the run and its timestamps; started_at and finished_at are null until they happen.

Response: 201 Queued run

{
  "id": "4c9e1b75-a2d8-4f60-8e13-b7d0a5c42f98",
  "customer_id": "0a6d3e8b-5c21-4f97-b4a0-8d1e7f93c256",
  "document_id": "d0e4b7a2-3f19-4c68-9a05-b1c7e8f26d34",
  "source_sha256": "9f2b6c0d4e8a1735b9c2d6f0a4e8b1c5372d9f0a6e4b8c2d1f5a7936e0b4c8d2",
  "page_number": 4,
  "input_id": "2f7c9a41-8b06-4d3e-a915-60c8e1d4b7a3",
  "engine_version": "v24-ts-pdfjs-1",
  "status": "queued",
  "attempts": 0,
  "created_by": "api:5d1c0e7a",
  "created_at": "2026-10-21T08:52:03.000Z"
}

cURL: Latest runs of a page through any copy of the file

curl "https://api.talonic.com/v1/chart-to-data/runs?source_sha256=$SHA256&page_number=4" \
  -H "Authorization: Bearer $TALONIC_API_KEY"
Fields that were never set, such as error_code, error_message, started_at and finished_at on a run that has just been queued, can be absent from the POST response instead of null. Treat absent and null alike.

Frequently asked questions

Why was a run accepted for a page that does not exist?+
Queuing never opens the file, so the page is checked when the worker executes the run. A page beyond the end of the PDF makes the run fail with PAGE_OUT_OF_RANGE; it is not an error on the POST.
Which inputs does a run use?+
The latest stored version for the file page at the time the run is queued, recorded as input_id. If there was none, the worker binds inputs when it executes: the latest stored one, else inputs derived from the page, else the run fails with INPUTS_MISSING. A run keeps its input_id, so rerunning the row is reproducible.
Are failed runs retried?+
Only transient failures, such as an unreadable file, up to a configured number of attempts. A lost job is re-queued by a recovery sweep, and a run stuck in running past the stale window returns to queued, or to failed with the code STALE once it has used its attempts. Engine refusals fail at once.

Related

Chart Extraction Overview
Prepared Inputs
Run Results & Integrity
Error Format