> ## 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 Ground Truth
> One dataset document's ground truth, keyed by field persistent_id
*Rate limit tier: **general**, 600 requests/min. See [Rate limits](/api-reference-v3/introduction#rate-limits).*
Reads the ground truth a dataset document packet holds: the expected value of every field, keyed by the field's `persistent_id`, as an [eval](/concepts/evals) grades it. Read it before you correct it with [Set ground truth](/api-reference-v3/datasets/set-ground-truth).
`document_packet_id` is the **dataset copy's** id: the one [Upload to dataset](/api-reference-v3/datasets/upload) returns, or the one [`GET …/evals/{eval_id}/accuracy/`](/api-reference-v3/evals/accuracy) lists in `by_document_packet`.
Omit `version` to read the workflow's current version, the one an eval grades by default; pass a `version_id` from [List workflow versions](/api-reference-v3/workflows/versions) to read another. `node_id` is the extract node's `id` in the [workflow graph](/api-reference-v3/workflows/get), and you need it only when the version has more than one extract node; without it such a version answers `422 EXTRACT_NODE_UNRESOLVED`. The response names the `version_id` and `node_id` it was read from. `ground_truth` is `null` until ground truth is first set for that version and node.
Any key with the `read` scope can read. Every `404 NOT_FOUND` names what is missing in `params.resource_type`: `document_packet` for an unknown packet or one in another organization, and `workflow_version` for an unknown version. A production packet answers `409 NOT_IN_DATASET`: only a dataset document packet holds ground truth.
```bash curl theme={null}
curl 'https://api.anyformat.ai/v3/document-packets/069dcc2c-e14c-7606-8000-2ee4fb17b4e1/ground-truth/' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
```python Python (SDK) theme={null}
from anyformat.sdk import Client
client = Client(api_key="YOUR_API_KEY")
stored = client.get_ground_truth("069dcc2c-e14c-7606-8000-2ee4fb17b4e1")
print(stored.version_id, stored.ground_truth)
```
```typescript TypeScript (SDK) theme={null}
import { Anyformat } from "@anyformat/sdk";
const af = new Anyformat({ apiKey: "YOUR_API_KEY" });
const stored = await af.getGroundTruth("069dcc2c-e14c-7606-8000-2ee4fb17b4e1");
```
```json Response (200 OK) theme={null}
{
"ground_truth": {
"0686bb978c3070f0800097669e00aaaa": "INV-001",
"0686bb978c3070f0800097669e00bbbb": [
{ "0686bb978c3070f0800097669e00cccc": "12.00" }
]
},
"version_id": "FGaV4I2JAA",
"node_id": "extract_1"
}
```
```json Response (200 OK, not set yet) theme={null}
{
"ground_truth": null,
"version_id": "FGaV4I2JAA",
"node_id": "extract_1"
}
```
## OpenAPI
````yaml GET /v3/document-packets/{document_packet_id}/ground-truth/
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-v3/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 (`/v3/`). Every response under
a versioned prefix includes `X-API-Version`.
version: 3.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: document-packets
description: >-
Document packets group uploaded documents for a workflow. Address a packet
directly to (re-)run its workflow.
- name: runs
description: >-
Extraction runs — the 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: splits
description: >-
Splits — the sub-documents a splitter node carves out of a packet.
Download any one of them as a PDF, built from the source documents on
request and never stored.
- name: parse
description: >-
Parse a single document with the platform's fast lite parse — a one-call
shortcut over the workflow upload + run primitives, backed by your
organization's system parse workflow.
- name: health
description: Health check endpoints to verify API availability.
paths:
/v3/document-packets/{document_packet_id}/ground-truth/:
get:
tags:
- datasets
summary: Get ground truth
description: >-
Read a dataset document packet's ground truth, keyed by field
`persistent_id`.
Omit `version` for the workflow's current version. `ground_truth` is
`null`
until it is first set for that version and node. An unknown packet, one
in
another organization, or an unknown version returns `404`;
`params.resource_type` says which. A production packet returns
`409 NOT_IN_DATASET`.
operationId: v3_get_ground_truth
parameters:
- name: document_packet_id
in: path
required: true
schema:
type: string
title: Document Packet Id
- name: version
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
A `version_id` from `GET /v3/workflows/{workflow_id}/versions/`.
Omit it for the workflow's current version, the one an eval grades
by default.
title: Version
description: >-
A `version_id` from `GET /v3/workflows/{workflow_id}/versions/`.
Omit it for the workflow's current version, the one an eval grades
by default.
- name: node_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
The extract node's `id` in the workflow graph, as `GET
/v3/workflows/{workflow_id}/` returns it. Required only when the
version has more than one extract node.
title: Node Id
description: >-
The extract node's `id` in the workflow graph, as `GET
/v3/workflows/{workflow_id}/` returns it. Required only when the
version has more than one extract node.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GroundTruthV3'
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
'400':
description: >-
Validation failed — the request body or query parameters are
invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
VALIDATION_ERROR:
value:
error: The request failed validation.
detail: The request failed validation.
error_code: VALIDATION_ERROR
retryable: false
request_id: req_abc123
'401':
description: >-
Authentication failed — the API key is not valid (`INVALID_API_KEY`)
or the request carries none (`MISSING_API_KEY`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INVALID_API_KEY:
value:
error: The API key is not valid.
detail: The API key is not valid.
error_code: INVALID_API_KEY
retryable: false
request_id: req_abc123
MISSING_API_KEY:
value:
error: The request carries no API key.
detail: The request carries no API key.
error_code: MISSING_API_KEY
retryable: false
request_id: req_abc123
'403':
description: >-
Access denied — the API key lacks access to this resource or the
scope this call needs (`ACCESS_DENIED`,
`insufficient_api_key_scope`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
ACCESS_DENIED:
value:
error: You do not have access to this resource.
detail: You do not have access to this resource.
error_code: ACCESS_DENIED
retryable: false
request_id: req_abc123
insufficient_api_key_scope:
value:
error: The API key does not carry the scope this call needs.
detail: The API key does not carry the scope this call needs.
error_code: insufficient_api_key_scope
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: The resource does not exist.
detail: The resource does not exist.
error_code: NOT_FOUND
retryable: false
request_id: req_abc123
'409':
description: '`NOT_IN_DATASET` — The document is not in the workflow''s dataset.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
NOT_IN_DATASET:
value:
error: The document is not in the workflow's dataset.
detail: The document is not in the workflow's dataset.
error_code: NOT_IN_DATASET
retryable: false
request_id: req_abc123
'422':
description: >-
`EXTRACT_NODE_UNRESOLVED` — The request does not say which extract
node to use. `detail` is a list of one `{type, loc, msg}`; `msg` is
`ambiguous` or `unknown`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
EXTRACT_NODE_UNRESOLVED:
value:
error: The request does not say which extract node to use.
detail:
- type: extract_node
loc:
- node_id
msg: ambiguous
error_code: EXTRACT_NODE_UNRESOLVED
retryable: false
request_id: req_abc123
'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: Too many requests.
detail: Too many requests.
error_code: RATE_LIMITED
retryable: true
request_id: req_abc123
'500':
description: >-
An internal error stopped the request — `retryable=true`. Retry with
backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INTERNAL_ERROR:
value:
error: An internal error stopped the request.
detail: An internal error stopped the request.
error_code: INTERNAL_ERROR
retryable: true
request_id: req_abc123
'502':
description: >-
An upstream service failed. Retry with backoff when `retryable` is
true.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INTERNAL_ERROR:
value:
error: An internal error stopped the request.
detail: An internal error stopped the request.
error_code: INTERNAL_ERROR
retryable: true
request_id: req_abc123
'503':
description: >-
An upstream service is unavailable. Retry with backoff when
`retryable` is true.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INTERNAL_ERROR:
value:
error: An internal error stopped the request.
detail: An internal error stopped the request.
error_code: INTERNAL_ERROR
retryable: true
request_id: req_abc123
'504':
description: An upstream service did not answer in time. Retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
GATEWAY_TIMEOUT:
value:
error: The upstream service did not answer in time.
detail: The upstream service did not answer in time.
error_code: GATEWAY_TIMEOUT
retryable: true
request_id: req_abc123
security:
- ApiKeyAuth: []
components:
schemas:
GroundTruthV3:
properties:
ground_truth:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Ground Truth
description: >-
The expected document, keyed by the workflow's field
`persistent_id`s. A scalar field maps to `string | null`; a table or
object field maps to an array of row objects keyed the same way.
`null` until ground truth is first set for this version and node.
examples:
- 0686bb978c3070f0800097669e00aaaa: INV-001
version_id:
type: string
title: Version Id
description: The workflow version the ground truth belongs to.
examples:
- FGaV4I2JAA
node_id:
type: string
title: Node Id
description: The extract node's `id` in the workflow graph.
examples:
- extract_1
type: object
required:
- ground_truth
- version_id
- node_id
title: GroundTruthV3
description: >-
A document packet's stored ground truth and the `(version, node)` it
belongs to.
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
- error_code
- retryable
- request_id
properties:
error:
type: string
description: Short human-readable summary.
detail:
description: >-
Machine-readable detail, any JSON value. A string for most errors, a
list of field errors for validation failures, and an object for a
structured error such as `FILENAME_CONFLICT` (`detail.conflicts`).
error_code:
type: string
enum:
- ACCESS_DENIED
- AGENTIC_MULTIFILE_UNSUPPORTED
- AUTH_FAILED
- CONCURRENT_EDIT
- DATASET_DOCUMENT_REJECTED
- DATASET_GROUND_TRUTH_SAVE_FAILED
- DATASET_INVALID_REQUEST
- EMPTY_EVAL
- ENDPOINT_RETIRED
- EXTRACT_MODE_FORBIDDEN
- EXTRACT_NODE_UNRESOLVED
- FILENAME_CONFLICT
- FILE_TOO_LARGE
- GATEWAY_TIMEOUT
- GRAPH_READBACK_FAILED
- GT_INVALID
- IDEMPOTENCY_KEY_REUSED
- IMMUTABLE_WORKFLOW
- INSUFFICIENT_CREDIT
- INTERNAL_ERROR
- INTERNAL_INCONSISTENCY
- INVALID_API_KEY
- INVALID_JSON
- INVALID_LOOKUP_FILE_ENCODING
- INVALID_VALUE
- INVALID_WORKFLOW_CONFIG
- KNOWLEDGE_NOT_ENABLED
- KNOWLEDGE_NOT_READY
- KNOWLEDGE_THREAD_MISMATCH
- KNOWLEDGE_UNSUPPORTED_SNAPSHOT_FORMAT
- LOOKUP_FIELD_WITHOUT_FILE
- METHOD_NOT_ALLOWED
- MISSING_API_KEY
- NOT_ACCEPTABLE
- NOT_FOUND
- NOT_IMPLEMENTED
- NOT_IN_DATASET
- OBJECT_STORAGE_UNAVAILABLE
- OPERATOR_DEPRECATED
- OPERATOR_NOT_AVAILABLE
- PARSE_MODE_FORBIDDEN
- PAYMENT_REQUIRED
- PRECONDITION_FAILED
- RATE_LIMITED
- REQUEST_TOO_LARGE
- RUN_IN_PROGRESS
- SPLIT_HAS_NO_PAGES
- SPLIT_SOURCE_NOT_PDF
- SPLIT_WORKFLOW_DATASET_UNSUPPORTED
- TOPOLOGY_INVALID
- UNSUPPORTED_FILE_TYPE
- UNSUPPORTED_LOOKUP_FILE
- UNSUPPORTED_MEDIA_TYPE
- UPLOAD_SNIFF_BUDGET_EXCEEDED
- VALIDATION_ERROR
- WORKFLOW_CONCURRENT_EDIT
- WORKFLOW_NAME_CONFLICT
- ZERO_DATA_RETENTION_REFUSES_DATASET
- ZERO_DATA_RETENTION_REFUSES_KNOWLEDGE
- deprecated_operator_ack_required
- insufficient_api_key_scope
- terms_acceptance_required
description: >-
Stable identifier for programmatic handling. New values can be added
at any time, so a client must accept a code it does not know.
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.
params:
type: object
additionalProperties: true
description: >-
Values specific to this occurrence of the error that a caller needs
to recover, such as `node_ids` or `required_scope`, keyed by name.
Absent when the code relays none.
doc_url:
type: string
format: uri
description: Link to the documentation of this `error_code`.
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/api-key. Send as `Authorization:
Bearer `.
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.