---
title: "Get this run's structured results (poll-able, per-document)"
method: GET
path: "/v1/run/{id}/results"
tags: ["Run"]
---

# Get this run's structured results (poll-able, per-document)

`GET /v1/run/{id}/results`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/run/{id}/results`
- Auth: HTTP bearer

The same governed results read as `GET /v1/pipelines/{id}/results` (review holdback, demoted-field projection, assembly awareness), scoped ALWAYS to this `/v1/run` request's own `documents[]` echo and ALWAYS the per-document view — "what did MY submitted documents produce," uniform across new/append pipeline modes. This is a deliberate DIVERGENCE from the per-run `run.completed` webhook, which for an unscoped non-append assembly run delivers COMPOSED rows: composed output for an assembly run is `GET /v1/pipelines/{id}/results?view=composed`, surfaced here at `links.composed_results` when a pipeline exists.

Only `document_id` and `include` filter the rows; `run_id`, `view`, `since`, `until`, and `status` are pipeline-route-only and 400 with `unsupported_filter` here, since the run IS the scope and its window is already bounded. `include=cells,provenance,audit` behave identically to the pipeline route — including the structured-subfield type projection on `fields`/`cells` and the raw, non-projected `audit` trail — see `GET /v1/pipelines/{id}/results` for the full shape and held-value redaction rules.

Two zero-states return `200` with an empty page and a `scope_note`, never `404`: no compiled pipeline exists yet for this run (still ingesting, or it failed before pipeline creation), or the run predates per-request document tracking (an echo-less legacy row, whose membership is unknowable). The envelope's `status` folds the same three-state vocabulary as `GET /v1/run/{id}` (`processing`/`completed`/`failed`) and DOES settle even for an append pipeline that never settles at the pipeline level — poll this route for append consumers instead of the pipeline route. Requires read scope.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `document_id` string
- `include` string
- `limit` integer
- `cursor` string

## Response `200`

This run's results page (always the documents view).

- RunResultsResponse
  - `run_id` string, uuid, required
  - `pipeline_id` string, uuid, nullable, required: Null while the run has no compiled pipeline yet.
  - `spec_id` string, uuid, required
  - `status` 'processing' | 'completed' | 'failed' | 'cancelled', required: The folded public run status (same vocabulary as GET /v1/run/{id}) — settles even for an append pipeline that never settles at the pipeline level.
  - `view` 'documents', required: Always documents on this route.
  - `generated_at` string, date-time, required
  - `columns` ResultsColumn[], required
    - `field_key` string, required: Stable machine key. Rows in `data` are keyed by this, never by the label.
    - `display_name` string, required: Human-readable column label, always present. A stored display name (a Spec field's title or a minted registry display name) wins; otherwise it is derived from `field_key`, e.g. `charge_type` → `Charge Type`.
    - `data_type` string, required
  - `data` ResultsRecord[], required
    - `document_id` string, uuid, nullable, required: Null only for an anchor-less composed row (the product record's anchor could not be resolved).
    - `filename` string, nullable, required
    - `run_id` string, uuid, nullable, required: The attributed /v1/run request id (echo containment, newest-for-pipeline fallback restricted to echo-less legacy rows); null for a UI or POST /v1/pipelines run.
    - `pipeline_id` string, uuid, required
    - `record_id` string, required: The row's record identity — the pipeline_document id on the main set, the product record id on the composed set.
    - `status` 'complete' | 'partial' | 'error' | 'processing', required: Folded from ~10 internal pipeline_documents states. Deliberately keeps partial (unlike GET /v1/run/{id}'s documents[].status, which folds partial into completed).
    - `completed_at` string, date-time, nullable, required: COALESCE of the last per-phase completion stamp. Tracks document PROCESSING completion, not value change — a review promotion or assembly recompose never advances it, and a phase rerun nulls it until the document re-processes.
    - `metadata` object: Caller tags; present only when set.
    - `batch_id` string: Present only when set.
    - `duplicate_of` object: Present only on a run-scoped duplicate occurrence (GET /v1/run/{id}/results, or the run_id filter) — the canonical whose bytes/OCR it reused, from the request's documents[] echo.
      - `id` string, uuid, required
      - `filename` string, nullable, required
    - `fields` object, required: field_key -> clean value. Held (pending_approval) fields serialize null; demoted fields and __ diagnostics are absent. A structured-subschema field is emitted TYPED (subfields projected to their declared data_type; number/boolean parse-miss -> null, enum/date miss and nested values -> raw), matching the cells[].value projection and the run.completed webhook.
    - `cells` object: Present only when include=cells. Keyed by field_key.
    - `provenance` object: Present only when include=provenance. Keyed by field_key.
    - `audit` object: Present only when include=audit. Keyed by field_key; the cell-version trail.
  - `pagination` ResultsPagination, required
    - `total` integer, required
    - `limit` integer, required
    - `has_more` boolean, required
    - `next_cursor` string, nullable, required: Opaque cursor keyed on record_id. Stable under concurrent appends.
  - `pending_review_count` integer, required
  - `scope_note` string: Present only for the two zero-states — no pipeline yet, or an echo-less legacy run.
  - `links` object, required
    - `self` string, required
    - `run` string, required
    - `composed_results` string: Present only when a pipeline exists — GET /v1/pipelines/{id}/results, where an assembly run's composed rows actually live.

## Other responses

- `400`: Invalid query parameters, or a pipeline-route-only filter (run_id, view, since, until, status) was supplied. code is one of invalid_document_ids, invalid_include, unsupported_filter, audit_include_too_broad.
- `401`: Missing or invalid API key.
- `404`: Run request not found.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)