Get Pipeline

Retrieve a document processing pipeline run by ID: its name, status, the Spec it ran against, compiled phase count, and links to progress and the dashboard.

GET /v1/pipelines/{id} retrieves a single document processing pipeline run by its UUID. The response carries the run's name, status, the Spec it ran against, the number of compiled phases, and a links object. Use this to confirm a run exists and read its top-level state before polling progress or producing a data product.

The status vocabulary is: active (documents are processing), paused, finalizing (every document is terminal and the pipeline-scoped tail — assembly, post-assembly resolution and validation, review triage — is still running), completed, and archived. The phase_count reflects how many phases the Spec rail compiled into for this run: a Spec with two resolution policies and a single validation checkpoint compiles to more phases than a bare extract-only Spec, so the count is a quick signal of how governed the run is.

Pass ?include=phases to also get the run's frozen phase plan — the configuration compiled at creation, which is what this run actually executed. This can differ from what the Spec compiles to today: a rail edit, a republish, or a new policy version changes future runs, never this one. Each entry is identity-only (execution order, phase_id, type, name, and the ids that join it to the rest of the API); execution configuration such as the extraction model stays internal.

The join key is rail_stage_id: the rail node each phase compiled from. It matches the nodes[] array on [GET /v1/specs/{id}](get-spec) — which compiles the CURRENT rail — so diffing the two lists tells you exactly how the Spec has drifted since this run. The same id is also the cost-attribution step_id on GET /v1/usage/pipelines/{id}, so per-phase spend lines up with the plan. Resolution phases additionally carry their policy_id, validation phases their validation_stage_id, and matching phases their matcher_stage_id.

For phase-by-phase document counts and per-document error detail, use GET /v1/pipelines/{id}/progress. To read extracted rows, poll [GET /v1/pipelines/{id}/results](get-pipeline-results) or produce a data product with POST /v1/pipelines/{id}/data-product. The run is tenant-scoped: a run that belongs to another organization returns 404 not_found. This endpoint requires an API key with the read scope.

curl https://api.talonic.com/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Lease Agreement — 2024-09-14",
  "status": "active",
  "schema": { "id": "sch_uuid_1" },
  "phase_count": 5,
  "created_at": "2024-09-14T10:32:00.000Z",
  "links": {
    "self": "/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "progress": "/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890/progress",
    "dashboard": "https://app.talonic.com/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

The frozen phase plan (include=phases)

curl "https://api.talonic.com/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890?include=phases" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "phase_count": 5,
  "phases": [
    { "number": 1, "phase_id": "phase-1", "type": "transfer",
      "name": "Transfer", "rail_stage_id": "stage-source-1" },
    { "number": 2, "phase_id": "phase-2", "type": "extraction",
      "name": "Extraction", "rail_stage_id": "stage-extraction-1" },
    { "number": 3, "phase_id": "phase-3", "type": "resolution",
      "name": "Normalize Currencies", "rail_stage_id": "stage-resolution-1",
      "policy_id": "9c2e4f6a-1b3d-5e7f-9a0b-2c4d6e8f0a1b" },
    { "number": 4, "phase_id": "phase-4", "type": "validation",
      "name": "Deposit Sanity Gate", "rail_stage_id": "stage-validation-1",
      "validation_stage_id": "5a7b9c1d-3e5f-7a9b-1c3d-5e7f9a1b3c5d" },
    { "number": 5, "phase_id": "phase-5", "type": "assembly",
      "name": "Assembly", "rail_stage_id": "stage-assembly-1", "scope": "pipeline" }
  ]
}

Errors