> ## 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.
# Get Run
> Fetch a single run flat: lifecycle status plus the results envelope inline
*Rate limit tier: **general** (600 req/min) — see [Rate limits](/api-reference-v3/introduction#rate-limits).*
Fetches a [run](/concepts/runs-and-results) by its `run_id`. The path is flat — no workflow id, no `/results/` sub-path — and the response carries the run's status **and** its results envelope in one shot, so a completed run is a single round-trip.
## Status model
The endpoint **always returns `200` while the run exists** — there are no precondition errors while the extraction is in flight.
| `status` | Meaning | `results` |
| ------------- | ------------------------------- | -------------------- |
| `queued` | Waiting for a processing slot | `null` |
| `in_progress` | Extraction actively running | `null` |
| `processed` | Success — terminal | the results envelope |
| `error` | Extraction failed — terminal | `null` |
| `cancelled` | Extraction cancelled — terminal | `null` |
Poll until `status` is terminal; a run that ended in `error` or `cancelled` stays readable with `results: null`. For production integrations, prefer [webhooks](/api-reference/webhooks/overview) over polling.
The `results` envelope matches the shape documented at [Response formats](/api-reference/response-formats) — the same `parse`, `classifications`, `splits`, and `extractions` sections v2 returned from its `/results/` route. It's the read path that changed, not the envelope.
Unknown ids — including runs belonging to another organization — return `404`.
```bash curl theme={null}
curl -X GET 'https://api.anyformat.ai/v3/runs/069dcc2c-e14c-7606-8000-2ee4fb17b4f9/' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
```python Python (requests) theme={null}
import requests
import time
run_id = "069dcc2c-e14c-7606-8000-2ee4fb17b4f9"
url = f"https://api.anyformat.ai/v3/runs/{run_id}/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
for _ in range(100):
run = requests.get(url, headers=headers).json()
if run["status"] == "processed":
print(run["results"])
break
if run["status"] in ("error", "cancelled"):
print(f"Terminal: {run['status']}")
break
time.sleep(3)
```
```typescript TypeScript theme={null}
interface RunDetail {
id: string;
workflow_id: string;
document_packet_id: string;
status: 'queued' | 'in_progress' | 'processed' | 'error' | 'cancelled';
created_at: string | null;
updated_at: string | null;
results: Record | null;
}
const runId = '069dcc2c-e14c-7606-8000-2ee4fb17b4f9';
const response = await fetch(`https://api.anyformat.ai/v3/runs/${runId}/`, {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const run: RunDetail = await response.json();
if (run.status === 'processed') {
console.log(run.results);
}
```
```json Response (200 OK — processed) theme={null}
{
"id": "069dcc2c-e14c-7606-8000-2ee4fb17b4f9",
"workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
"document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
"status": "processed",
"created_at": "2026-07-01T12:00:00.000Z",
"updated_at": "2026-07-01T12:02:30.000Z",
"results": {
"parse": {
"markdown": "..."
},
"classifications": [],
"splits": [],
"extractions": [
{
"split_name": null,
"partition": null,
"fields": {
"invoice_number": {
"value": "INV-001",
"value_override": null,
"verification_status": "not_verified",
"confidence": 95.0,
"evidence": [{ "text": "Invoice #INV-001", "page_number": 1 }]
}
}
}
]
}
}
```
```json Response (200 OK — still processing) theme={null}
{
"id": "069dcc2c-e14c-7606-8000-2ee4fb17b4f9",
"workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
"document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
"status": "in_progress",
"created_at": "2026-07-01T12:00:00.000Z",
"updated_at": "2026-07-01T12:00:15.000Z",
"results": null
}
```
```json Response (200 OK — terminal, no results) theme={null}
{
"id": "069dcc2c-e14c-7606-8000-2ee4fb17b4f9",
"workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
"document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
"status": "error",
"created_at": "2026-07-01T12:00:00.000Z",
"updated_at": "2026-07-01T12:02:30.000Z",
"results": null
}
```
## OpenAPI
````yaml GET /v3/runs/{run_id}/
openapi: 3.1.0
info:
title: anyformat API
description: >
Document extraction and workflow automation API.
AnyFormat lets you define extraction workflows that pull structured data
from any document — PDFs, images, scanned files, or plain text. Upload a
file, run it through a workflow, and get back structured fields with
confidence scores and source evidence.
## Quick start
See the [Quick start
guide](https://docs.anyformat.ai/api-reference/introduction) for a
walkthrough.
## Authentication
All endpoints (except `/health/`) require a Bearer token in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from
[app.anyformat.ai/api-key](https://app.anyformat.ai/api-key).
## Versioning
Endpoints are versioned by path prefix (`/v2/`, `/v3/`). Every response
under
a versioned prefix includes `X-API-Version`.
version: 2.0.0
servers:
- url: https://api.anyformat.ai
description: API server
security: []
tags:
- name: workflows
description: >-
Workflows define extraction templates — what fields to extract from
documents. Create workflows, upload files, run extractions, and fetch
results.
- name: files
description: >-
File collections group uploaded documents and track their extraction
progress. Upload files, check status, and retrieve extraction results.
- name: suggestions
description: >-
AI-powered schema and workflow suggestion endpoints for the AnyFormat
webapp. Authenticated with a Cognito JWT rather than an API key.
- name: document-packets
description: >-
Document packets group uploaded documents for a workflow (v3). Address a
packet directly to (re-)run its workflow.
- name: runs
description: >-
Extraction runs — the v3 first-class result entity. Each run is a single
execution of a workflow against a document packet; fetch its status and
results flat by run id.
- name: health
description: Health check endpoints to verify API availability.
paths:
/v3/runs/{run_id}/:
get:
tags:
- runs
summary: Get run
description: |-
Retrieve one run flat: lifecycle status plus results inline.
Always 200 while the run exists — no precondition errors while the
extraction is in flight. `results` is `null` until `status` reaches
`processed`, then carries the extraction results envelope (the same
shape as the v2 results endpoint). A run that ended in `error` or
`cancelled` stays readable with `results: null`.
Unknown ids — including runs belonging to another organization —
return 404.
operationId: v3_get_run
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunDetailV3'
headers:
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
'401':
description: Authentication failed — missing, invalid, or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
AUTH_FAILED:
value:
error: Authentication failed.
detail: Authentication failed.
error_code: AUTH_FAILED
retryable: false
request_id: req_abc123
'404':
description: >-
Resource not found — the workflow, document packet, or run ID does
not exist or is not visible to this API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
NOT_FOUND:
value:
error: Resource not found.
detail: Resource not found.
error_code: NOT_FOUND
retryable: false
request_id: req_abc123
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: >-
Rate limited — retry after the `Retry-After` header. Default
windows: 60 requests/minute for extraction submission, 600
requests/minute for general endpoints.
headers:
Retry-After:
description: Seconds until the next request is allowed.
schema:
type: integer
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
RATE_LIMITED:
value:
error: Rate limit exceeded — retry after backoff.
detail: Rate limit exceeded — retry after backoff.
error_code: RATE_LIMITED
retryable: true
request_id: req_abc123
security:
- ApiKeyAuth: []
components:
schemas:
RunDetailV3:
properties:
id:
type: string
title: Id
description: Unique identifier of the run (hyphenated UUID).
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4f9
workflow_id:
type: string
title: Workflow Id
description: The workflow this run executed (hyphenated UUID).
examples:
- 0686bb97-8c30-70f0-8000-97669e000eb8
document_packet_id:
type: string
title: Document Packet Id
description: The document packet the run executed on (hyphenated UUID).
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4e1
status:
$ref: '#/components/schemas/RunStatus'
description: >-
Execution status. Non-terminal: `queued`, `in_progress`. Terminal:
`processed` (success), `error`, `cancelled`.
examples:
- processed
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: Timestamp when the run was triggered (ISO 8601).
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
description: Timestamp of the run's last status change (ISO 8601).
results:
anyOf:
- $ref: '#/components/schemas/ResultsResponse'
- type: 'null'
description: >-
Extraction results envelope; `null` until `status` is `processed`.
Same shape as the v2 results endpoint.
type: object
required:
- id
- workflow_id
- document_packet_id
- status
title: RunDetailV3
description: |-
Flat single-run read: lifecycle status plus results inline.
`results` is `null` until the run reaches `processed`, then carries the
same results envelope `GET /v2/workflows/{id}/files/{id}/results/`
returns — no separate results endpoint, no 412 while in flight.
ErrorEnvelope:
type: object
title: ErrorEnvelope
description: >-
Uniform error response. `retryable=true` means the same request may
succeed on retry (with backoff); `retryable=false` means the caller must
change the request before retrying.
required:
- error
- detail
- error_code
- retryable
- request_id
properties:
error:
type: string
description: Short human-readable summary.
detail:
description: >-
Machine-readable detail. String for most errors; list of field
errors for validation failures.
oneOf:
- type: string
- type: array
items:
type: object
error_code:
type: string
description: Stable identifier for programmatic handling.
examples:
- VALIDATION_ERROR
- AUTH_FAILED
- NOT_FOUND
- PRECONDITION_FAILED
- RATE_LIMITED
- INTERNAL_ERROR
- GATEWAY_TIMEOUT
retryable:
type: boolean
description: True when the caller should retry (with backoff for 429/412/5xx).
request_id:
type: string
description: Correlates this response with server logs.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
RunStatus:
type: string
enum:
- queued
- in_progress
- processed
- error
- cancelled
title: RunStatus
description: |-
Execution lifecycle of a run. Non-terminal: ``queued``,
``in_progress``. Terminal: ``processed`` (success), ``error``,
``cancelled``.
ResultsResponse:
properties:
collection_id:
type: string
title: Collection Id
description: >-
The file collection's UUID. Same value as the `id` returned by `POST
/v2/workflows/{wid}/run/`.
verification_url:
anyOf:
- type: string
- type: 'null'
title: Verification Url
description: >-
Link to the AnyFormat dashboard for human review of this
collection's results. `null` if the dashboard URL cannot be
constructed (e.g. no files in the collection, or the deployment has
no frontend URL configured).
parse:
anyOf:
- $ref: '#/components/schemas/ParseResult'
- type: 'null'
description: >-
Parse-node output (rendered markdown). `null` when the workflow has
no parse node. Always present in the response.
classifications:
items:
$ref: '#/components/schemas/ClassificationResult'
type: array
title: Classifications
description: >-
Per-classifier-node verdicts. Empty when the workflow has no
classifier.
splits:
items:
$ref: '#/components/schemas/SplitResult'
type: array
title: Splits
description: >-
Splitter output: category-level geometry with optional partitions.
Empty when the workflow has no splitter.
extractions:
items:
$ref: '#/components/schemas/Extraction'
type: array
title: Extractions
description: >-
Flat list of extraction datapoints. Linear workflows produce one
entry with `split_name=null` and `partition=null`. Split workflows
produce one entry per (split, partition). Empty when no extraction
has run yet.
extraction:
anyOf:
- additionalProperties:
anyOf:
- $ref: '#/components/schemas/ExtractedField'
- items:
additionalProperties:
$ref: '#/components/schemas/ExtractedField'
type: object
type: array
type: object
- type: 'null'
title: Extraction
description: >-
**Deprecated** — use `extractions` instead. Extracted fields keyed
by field name, populated only for linear workflows (single extract
node, no splitter). `null` for split workflows; read `extractions[]`
instead.
deprecated: true
type: object
required:
- collection_id
title: ResultsResponse
description: >-
Canonical response shape for the file-collection results endpoint.
Returned with HTTP 200 once processing completes. Returns 412 while
processing is
in progress; poll until 200, or use webhooks.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
ParseResult:
properties:
markdown:
anyOf:
- type: string
- type: 'null'
title: Markdown
description: >-
Document content rendered as structured markdown. Each block is
preceded by an empty `` anchor (invisible
in any markdown renderer; the id joins to `blocks[].id` and can be
used as an in-page link target). Image hydration for picture/figure
blocks happens client-side. `null` if parsing failed.
text:
anyOf:
- type: string
- type: 'null'
title: Text
description: >-
Plain markdown with structural HTML removed — `` framing,
block anchors, `![]()
` tags, and `` wrappers
stripped. Useful when feeding the parsed output into an LLM or a
search index that doesn't need the block-level metadata. `null` if
`markdown` is null.
layout_confidence:
anyOf:
- type: number
- type: 'null'
title: Layout Confidence
description: >-
Document-level YOLO layout confidence on a 0-100 scale,
char-weighted mean across all blocks. `null` if no annotated
sections.
parse_confidence:
anyOf:
- type: number
- type: 'null'
title: Parse Confidence
description: >-
Document-level parse confidence on a 0-100 scale, char-weighted mean
of per-block LLM logprob scores. `null` when no blocks have
logprob-based confidence.
blocks:
items:
$ref: '#/components/schemas/Block'
type: array
title: Blocks
description: >-
Structured per-block representation of the parsed document. One
entry per `` anchor in document order, with type-specific
structured data (`rows` for tables, `image_base64` for pictures)
surfaced as first-class fields so consumers don't have to
HTML-parse.
type: object
required:
- markdown
title: ParseResult
description: Parsed markdown for a file.
ClassificationResult:
properties:
category:
type: string
title: Category
description: The category the document was classified as.
confidence:
type: number
title: Confidence
description: 0-100 model confidence in the verdict.
evidence:
anyOf:
- type: string
- type: 'null'
title: Evidence
description: >-
Free-form evidence text (the snippets the classifier cited). `null`
when none captured.
type: object
required:
- category
- confidence
title: ClassificationResult
description: One classifier verdict for the collection.
SplitResult:
properties:
name:
type: string
title: Name
description: The split's category name.
files:
items:
$ref: '#/components/schemas/FilePages'
type: array
title: Files
description: Per-file page lists, union of all partitions.
confidence:
type: integer
title: Confidence
description: 0-100 aggregate confidence (min across partitions).
partitions:
items:
$ref: '#/components/schemas/SplitPartition'
type: array
title: Partitions
type: object
required:
- name
- files
- confidence
title: SplitResult
description: |-
A category-level split: which pages of which files fall under it, plus
any partitions inside it. Extraction data lives under `extractions[]` —
join by `split_name`.
Extraction:
properties:
split_name:
anyOf:
- type: string
- type: 'null'
title: Split Name
description: >-
The split category this extraction belongs to. `null` for linear
workflows.
partition:
anyOf:
- type: string
- type: 'null'
title: Partition
description: >-
The partition value within the split. `null` when the split has no
partitions.
fields:
additionalProperties:
anyOf:
- $ref: '#/components/schemas/ExtractedField'
- items:
additionalProperties:
$ref: '#/components/schemas/ExtractedField'
type: object
type: array
type: object
title: Fields
description: >-
Extracted fields keyed by field name. Same shape as the legacy
top-level `extraction`.
type: object
required:
- fields
title: Extraction
description: >-
One unit of extracted data. For linear (parse->extract) workflows there
is exactly one entry with `split_name=null` and `partition=null`. For
split
workflows there is one entry per (split, partition) pair; join with
`splits[]` by `split_name` to look up geometry.
ExtractedField:
properties:
value:
anyOf:
- {}
- type: 'null'
title: Value
description: >-
The extracted value. Type depends on the field's `data_type`
(string, number, date, etc.). `null` when extraction could not
produce a value.
value_override:
anyOf:
- {}
- type: 'null'
title: Value Override
description: >-
A human-supplied override of the extracted `value`, if one was set
during verification. `null` when no override exists.
verification_status:
anyOf:
- type: string
- type: 'null'
title: Verification Status
description: >-
Verification state for this datapoint (e.g. `not_verified`,
`verified`). `null` when not yet reviewed.
confidence:
anyOf:
- type: number
- type: 'null'
title: Confidence
description: >-
Model confidence in the extracted value, on a 0-100 scale. `null`
when the backend did not produce a confidence (e.g. manual entry).
evidence:
items:
$ref: '#/components/schemas/Evidence'
type: array
title: Evidence
description: Source-text snippets the model used to derive this value.
type: object
required:
- value
title: ExtractedField
description: One extracted field's value, confidence, and supporting evidence.
Block:
properties:
id:
type: string
title: Id
description: Stable block identifier in the form `p_b`.
type:
type: string
title: Type
description: >-
Semantic type: `text`, `title`, `section-header`, `table`,
`picture`, `other`.
page:
type: integer
title: Page
description: 1-indexed page number this block belongs to.
bbox:
additionalProperties:
type: number
type: object
title: Bbox
description: >-
Normalised bounding box in [0, 1] page coordinates with keys
`x0`/`y0`/`x1`/`y1`.
layout_confidence:
type: number
title: Layout Confidence
description: 0-100 YOLO layout detection confidence for this block.
parse_confidence:
anyOf:
- type: number
- type: 'null'
title: Parse Confidence
description: >-
0-100 parse confidence calibrated from LLM logprobs. `null` when
logprobs were unavailable (e.g. text-bytes strategy).
content:
type: string
title: Content
description: >-
Raw section body — markdown for text/title blocks, HTML for tables,
`` for pictures.
hyperlinks:
items:
$ref: '#/components/schemas/Hyperlink'
type: array
title: Hyperlinks
description: Hyperlinks found in the content via `[text](uri)` markdown syntax.
rows:
anyOf:
- items:
items:
additionalProperties:
type: string
type: object
type: array
type: array
- type: 'null'
title: Rows
description: >-
2D array of table cells for `type=table` blocks — each cell is
`{cell_id, text}`. `null` for non-table blocks.
image_base64:
anyOf:
- type: string
- type: 'null'
title: Image Base64
description: >-
Inline base64-encoded cropped image for `type=picture` blocks.
Currently `null` for all blocks — image hydration is performed
client-side by the SDK consumer.
type: object
required:
- id
- type
- page
- bbox
- layout_confidence
- content
title: Block
description: |-
One semantic block of a parsed document — a structured alternative to
walking `` anchors in `markdown`.
All blocks expose the common fields (`id`, `type`, `page`, `bbox`,
`confidence`, `content`). Type-specific structured data lives in the
optional fields (`rows` for tables, `image_base64` for pictures).
Consumers can switch on `type` to access the per-type fields, or treat
`content` as the universal fallback.
FilePages:
properties:
file_id:
type: string
title: File Id
description: The file's UUID.
file_name:
type: string
title: File Name
description: The file's display name.
pages:
items:
type: integer
type: array
title: Pages
description: 1-indexed page numbers from this file.
type: object
required:
- file_id
- file_name
- pages
title: FilePages
description: A file's contribution of pages to a split or partition. 1-indexed.
SplitPartition:
properties:
name:
type: string
title: Name
description: The partition value (free-form string).
files:
items:
$ref: '#/components/schemas/FilePages'
type: array
title: Files
confidence:
type: integer
title: Confidence
description: 0-100 minimum confidence across the partition's ranges.
type: object
required:
- name
- files
- confidence
title: SplitPartition
description: >-
A partition value within a split (e.g. `1234-5678` under `Account
Holdings`).
Evidence:
properties:
text:
type: string
title: Text
description: The exact source-text snippet that supports the extracted value.
page_number:
type: integer
title: Page Number
description: 1-indexed page number where the snippet was found.
type: object
required:
- text
- page_number
title: Evidence
description: >-
A snippet of source text supporting an extracted value, with the page it
came from.
Hyperlink:
properties:
text:
type: string
title: Text
description: The display text of the link.
uri:
type: string
title: Uri
description: The link target (URL, mailto:, etc.).
type: object
required:
- text
- uri
title: Hyperlink
description: A hyperlink found inside a block's content.
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/api-key. Send as `Authorization:
Bearer `.
scheme: bearer
````