> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Runs & results
> What happens when you run a workflow on a document, and the shape of what comes back: one section per atomic operation.
Start a run by submitting a document. Use the UI, or call [`POST /v3/workflows/{workflow_id}/upload/run/`](/api-reference-v3/workflows/upload-and-run), which uploads and runs in one call. Or [upload](/api-reference-v3/workflows/upload) a packet first and [run it](/api-reference-v3/document-packets/run) separately. anyformat creates a **[document packet](/concepts/document-packets)** to hold the document, walks the workflow graph, and writes structured **results**.
***
## Run lifecycle
Every run moves through a sequence of statuses:
| Status | Description |
| - | - |
| `queued` | Waiting for an available processing slot |
| `in_progress` | Processing is actively running |
| `processed` | Processing complete, results available (terminal) |
| `error` | Processing failed (terminal) |
| `cancelled` | Processing was cancelled (terminal) |
A run only exists once it is triggered, so runs start at `queued`. Before that, the [document packet](/concepts/document-packets) carries `status: not_started`.
Read a run with [`GET /v3/runs/{run_id}/`](/api-reference-v3/runs/get). It always returns **200 OK** with the status above. `results` is `null` until the run reaches `processed`, then the results envelope arrives inline on the same read. Poll until the status is terminal, then stop.
A run reads the same way at every status. Only two keys change:
```json A run being polled highlight={3,4} theme={null}
{
"id": "06a9571c-943f-762e-8000-99039eaf9823",
"status": "in_progress",
"results": null
}
```
[What the results contain](#what-the-results-contain) below writes the envelope out in full.
## What the results contain
This page is the one place the whole envelope is written out. Every other page shows the few
lines its own topic needs and links back here.
A run produces **one output section per node type that ran**. The envelope has a fixed shape.
A section for a node you did not include comes back empty, `null` or `[]`, so your code reads
every key without checking first.
```json The shape highlight={5,7} theme={null}
{
"id": "06a9571c-943f-762e-8000-99039eaf9823",
"status": "processed",
"results": {
"parse": { "markdown": "…", "blocks": ["…"] },
"classifications": [],
"extractions": [{ "fields": { "…": "…" } }],
"splits": [],
"edits": [],
"extraction": { "…": "…" }
}
}
```
Line 6 is what the document says. Line 8 is what you asked for. The rest are sections this
workflow did not use. It had a Parse node and an Extract node, so `classifications`,
`splits` and `edits` are empty. `extraction` is the deprecated flat copy of a linear workflow's
fields. Read `extractions[]` instead.
Trimmed only where a value is long: `markdown` runs to the length of the document, and `blocks`
carries one entry per block on every page.
```json theme={null}
{
"id": "06a9571c-943f-762e-8000-99039eaf9823",
"workflow_id": "06a9571c-88c8-7a5c-8000-76b0c61462eb",
"document_packet_id": "06a9571c-9438-713d-8000-d30bb424818a",
"status": "processed",
"created_at": "2026-08-31T12:19:04.132409Z",
"updated_at": "2026-08-31T12:20:31.884201Z",
"results": {
"document_packet_id": "06a9571c-9438-713d-8000-d30bb424818a",
"verification_url": "https://app.anyformat.ai/workflows/06a9571c-88c8-7a5c-8000-76b0c61462eb/files/06a9571c-9441-7a0e-8000-5c2a1f0b9d34?versionId=FGaV4I2JAA",
"parse": {
"markdown": "\n\n# INVOICE\n\n\n\nInvoice #: INV-2026-9001 \nIssue date: 2026-02-20 \n…",
"text": "# INVOICE\n\nInvoice #: INV-2026-9001 …",
"parse_confidence": 89.6,
"layout_confidence": 0.7,
"blocks": [
{
"id": "p1_b0",
"type": "title",
"page": 1,
"bbox": { "x0": 0.1148, "y0": 0.0665, "x1": 0.2692, "y1": 0.096 },
"parse_confidence": 100.0,
"layout_confidence": 0.846,
"content": "# INVOICE",
"hyperlinks": [],
"rows": null,
"image_base64": null
}
]
},
"classifications": [],
"splits": [],
"extractions": [
{
"split_name": null,
"partition": null,
"fields": {
"vendor_name": {
"value": "Wayne Enterprises",
"value_override": null,
"verification_status": "not_verified",
"confidence": 97.0,
"evidence": [
{ "text": "From: Wayne Enterprises\n148 Eric Track, New Stephanie, NC 00575", "page_number": 1 }
]
},
"supplier_id": {
"value": "SUP-1042",
"value_override": null,
"verification_status": "not_verified",
"confidence": null,
"evidence": []
}
},
"validations": []
}
],
"edits": [],
"extraction": { "vendor_name": "…" }
}
}
```
Two fields are shown, from a workflow that used [Smart lookup](/guides/nodes/smart-lookup).
`vendor_name` was read off the page, so it carries a confidence and the phrase it came from.
`supplier_id` was resolved from a reference file, so its `confidence` is `null` and its
`evidence` is empty. There is no page it was read from.
| Section | From which node | Shape |
| - | - | - |
| `verification_url` | none | Link to the Studio review page for the packet's first file, pinned to the workflow version the run used: `https://app.anyformat.ai/workflows//files/?versionId=`. `null` when the packet has no file. |
| `parse` | the parse node | `markdown` holds the whole document, with an `` anchor before each block and HTML `` elements. Also `text`, `parse_confidence`, `layout_confidence`, and `blocks[]`, the same content block by block with page, bbox, and confidences. See [Parse](/guides/nodes/parse#what-it-returns). `null` if the workflow has no parse node, which is rare because the topology requires parse. |
| `classifications` | classify nodes | Array of `{category, confidence, evidence}`. Empty when no classifier ran. |
| `splits` | the splitter node | Array of `{name, files, confidence, partitions}` describing the segments. Empty when no splitter ran. |
| `extractions` | extract nodes | Array of `{split_name, partition, fields, validations}`. A linear workflow produces one untagged entry. A branched or split workflow produces one entry per `(split, partition)`. Empty when no extract ran, as in a parse-only workflow. |
| `extractions[].validations` | the Validate node | Array of `{rule_id, description, severity, status, detail, compared_values, source_fields}`, one per rule, on the extraction entry the rules judged. `status` is `pass`, `fail`, or `inconclusive`. Empty when no Validate node ran. |
| `edits` | the Edit node | Array of `{file_id, file_name, fields, unmatched_instructions, download_url}`. One entry per file the node filled. Empty when no Edit node ran. |
| `extraction` | extract nodes (legacy) | **Deprecated.** Flat `{field_name → ExtractedField}` dict, populated only for linear workflows. Kept for backward compatibility. New code reads `extractions[]`. It will be removed in a future major version. |
Each extracted field carries a `value`, an optional human-supplied `value_override`, a `confidence` score from 0 to 100, a `verification_status`, and an `evidence` array of source-text snippets with page numbers. [Get run](/api-reference-v3/runs/get) documents the full envelope. Read `value_override` when it is set, and `value` otherwise.
**What the SDKs give you back.** The [TypeScript](/api-reference-v3/sdks/typescript) and [Python](/api-reference-v3/sdks/python) SDKs both return a `Result` from `Run.wait()`. For a linear `parse → extract` workflow the scalar values sit right there. In Python, read `result.fields["name"].value`. In TypeScript, read `result.field("name")?.value`. The full envelope lives at `result.raw` in both languages: parse markdown, classifications, splits, and multi-extraction entries. Python also exposes a typed `result.parse` view.
***
## Filled forms
An [Edit node](/guides/nodes/overview) produces a document rather than data, so its output lands in its own section: `edits[]`, one entry per file the node processed. A packet of five blank forms comes back as five entries.
Each entry records which fields the node found and what it wrote into them:
* **`fields`**: every form field detected, filled or not, in document order. A field carries its printed `label`, its `kind` of `text` or `checkbox`, the `page` and `bbox` it occupies, and the `value` written into it. A field the document already carried a value for comes back as `state: "prefilled"`. anyformat never overwrites it, so it always reads back with `value: null`.
* **`unmatched_instructions`**: the instruction fragments, quoted verbatim, that the linker matched to no field in this document. It covers instructions that found no field, not every reason a value can be missing from the rendered PDF, so treat the filled document itself as the final word.
* **`download_url`**: a temporary link to the filled PDF.
**The download link is short-lived.** `download_url` is valid for **15 minutes** from the moment the response was built. A fresh one is minted every time you read the run. Fetch the PDF when you receive it, or re-read the run for a new link. A stored URL will be dead.
***
## Confidence and evidence
Two signals that travel with most outputs.
### Confidence
A 0–100 score indicating how certain anyformat is about a value.
* For `parse`: two document-level scores, plus the same pair on every entry of `blocks[]`. `parse_confidence` runs 0 to 100 and grades the **text** anyformat read. `layout_confidence` runs 0 to 1 and grades the **page layout** it detected. `parse_confidence` comes from the language model's token log-probabilities. On a table block it is the mean of the confidence of its cells that carry text, so it reads as the expected fraction of those cells read correctly; blank cells do not enter the mean, and it is `null` when no cell carries text. `layout_confidence` comes from the YOLO layout-segmentation model.
* For `extractions`: a per-field score on each extracted value.
* For `classifications`: a per-verdict score.
* For `edits`: a per-field score with a different meaning from the rest. It grades how surely a filling instruction addressed that field, not whether the value written in is correct. It is raw and uncalibrated, and it is not a probability. Treat it as a ranking signal for review, not as a quality score for the filled document.
### Evidence
An **array** of metadata objects showing where a value came from.
It is an array because some values are **inferred** across several spans rather than copied from one place. Each evidence object has:
* The **snippet of text** the value came from
* The **page number** in the document
Evidence is the right signal to surface in a human-review UI. It lets reviewers jump straight to the source.
**Metadata-sourced values carry a marker.** When a field comes from a top-level key of the [packet's `metadata`](/concepts/document-packets#attaching-metadata) rather than from the document, `evidence[0].text` is `metadata.`, such as `metadata.customer_reference`. A value taken from free-text metadata carries `metadata.__anyformat_free_text__`. Key on that prefix client-side to render metadata provenance differently, or to route the value to a "verified upstream" path. There is no page number to plot.
***
## What's next?
Export formats for results: CSV, Excel, JSON, Markdown
Upload a document and start a run in one call
The flat read that returns a run with its results inline
The unit a workflow runs on
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.