talonic_run_spec
Run a Spec — the customer's configured pipeline — over a set of documents in one call. Provide exactly one of document_ids (documents already in the workspace) or file_urls (public https files, max 20 — Talonic ingests them first). The call returns a RunEnvelope that normalizes two different backends (/v1/pipelines for document_ids, /v1/run for file_urls) into one shape, so the agent never has to know which route ran — only which id to poll with: poll talonic_get_run with pipeline_id when run_kind is pipeline, or with run_id when it is run. Running a Spec consumes credits.
Documents not yet in the workspace:
talonic_request_upload → poll talonic_get_document → talonic_run_spec with document_ids. Remote public files: file_urls (max 20).When to use
- The user wants to run their configured pipeline (a Spec) over documents.
- You need to process files through a Spec and produce its structured rows.
- You already have a
spec_idfromtalonic_list_specsand either workspace documents or public file URLs.
When not to use
- One-off extraction with an ad-hoc schema — use
talonic_extract. - Checking progress on a run already started — use
talonic_get_run. - Reading a completed run's rows — use
talonic_get_run_results.
Parameters
| Parameter | Type | Description |
|---|---|---|
| spec_id * | string | Spec UUID (from `talonic_list_specs`). |
| document_ids | string[] | Workspace document ids (1–500). Mutually exclusive with `file_urls`. |
| file_urls | string[] | Public https file URLs (1–20). Mutually exclusive with `document_ids`. |
| name | string | Display name for the run. |
| pipeline_mode | string | `new` (default) or `append` to the Spec's existing pipeline. |
| batch_id | string | Caller grouping key. Only applies to the `file_urls` path. |
| metadata | object | Flat caller tags stamped on every ingested document. Only applies to the `file_urls` path. |
Response shape
Fields
| Parameter | Type | Description |
|---|---|---|
| run_kind | string | `pipeline` (document_ids route) or `run` (file_urls route). |
| run_id | string|null | Run id when `run_kind` is `run`; null otherwise. |
| pipeline_id | string|null | Pipeline id when `run_kind` is `pipeline`; null otherwise. |
| spec_id | string | The Spec that ran. |
| spec_name | string|null | The Spec's display name, when the backend returned one; null otherwise. |
| status | string | `processing`, `completed` or `failed`, normalized across both backends. |
| raw_status | string|null | The backend's own status string, unnormalized. |
| input_count | number | Number of documents or URLs submitted. |
| enqueued_documents | number|null | Documents enqueued for processing on the `document_ids` route; absent on the `file_urls` route. |
| appended | boolean | Whether this run appended to the Spec's existing pipeline (`pipeline_mode: 'append'`); present on the `document_ids` route only. |
| documents[] | array | Per-document detail, present on the `file_urls` route. |
| message | string|null | Informational message from the API, e.g. 'Pipeline created and queued for processing.'; null when not provided. |
| links | object | Follow-up URLs, e.g. a poll link. |
Frequently asked questions
Does this cost credits?+
Yes — ingestion/OCR and extraction meter credits per document exactly as a run started in the app does; validation and delivery stages are free. Check `talonic_get_pricing` and `talonic_get_balance` before a large batch.