talonic_get_spec
Get one Spec's full structure: identity and version state, the schema it materializes onto, nodes[] — the rail as authored, in editing order — and phases[] — the compiled execution plan, in run order. A validation checkpoint expands to one phase per gate, so the two lists differ on purpose. fields[] maps Spec fields to schema fields. Pass include_versions to also fetch versions[], the Spec's published version history, newest first.
When to use
- You need to explain what a run will do before starting it.
- You want to confirm a Spec is published (
versionnon-null) before callingtalonic_run_spec. - You need to map Spec field names to schema field keys.
When not to use
- You want to list all Specs — use
talonic_list_specs. - You are ready to execute the pipeline — use
talonic_run_spec.
Parameters
| Parameter | Type | Description |
|---|---|---|
| spec_id * | string | Spec UUID (from `talonic_list_specs`). |
| include_versions | boolean | Also fetch the published versions list (adds `versions[]`). |
Response shape
Fields
| Parameter | Type | Description |
|---|---|---|
| id | string | Spec UUID. |
| name | string | Spec name. |
| version | number|null | Published version number, or null if never published. |
| materialized_version | number|null | Version currently materialized onto the schema, or null. |
| schema.id | string | The schema this Spec materializes onto. |
| nodes[].type | string | Stage type in the authored rail: one of `source`, `registry`, `schema`, `resolve`, `valid`, `assembly`, `deliver`, `reconcile`, `sanitize`, `triage`, `switch`. |
| nodes[].name | string | Node display name. |
| phases[].number | number | Phase order in the compiled execution plan. |
| phases[].type | string | Compiled phase type, derived from the rail stage it came from (`rail_stage_id` joins back to `nodes[].node_id`); Source and Data Product stages produce no phase, and a validation checkpoint expands to one phase per gate. |
| phases[].name | string | Phase display name. |
| fields[].name | string | Spec field name, mapped to its schema field. |
| versions[].version | number | Published version number (present when `include_versions` is true). |
| versions[].is_materialized | boolean | Whether this version is the one currently materialized onto the schema. |
Frequently asked questions
Why do nodes and phases differ?+
`nodes[]` is the rail as authored, in editing order; `phases[]` is the compiled execution plan, in run order. A validation checkpoint expands into one phase per gate, so a single authored node can produce several phases — the two lists differ on purpose.