> ## 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.
# List Evals
> List a workflow's evals, newest first
*Rate limit tier: **general** (600 req/min) — see [Rate limits](/api-reference-v3/introduction#rate-limits).*
Returns one keyset page of a workflow's [evals](/concepts/evals), newest first. Follow `next_cursor` until it is `null` (see [Pagination](/api-reference-v3/introduction#pagination)).
Each item is the **same headline** [`GET /v3/workflows/{workflow_id}/evals/{eval_id}/`](/api-reference-v3/evals/get) returns — `run_number`, grading `status`, `accuracy` and its `matched` / `mismatched` / `ungraded` tallies, `file_count`, and `failed_count`. The headline fields are `null` on any item still `in_progress` (see [its status model](/api-reference-v3/evals/get#status-model)), so a fresh page can mix graded and running evals.
An unknown workflow — including one in another organization — returns `404`.
```bash curl theme={null}
curl -X GET 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/evals/?limit=20' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
```python Python (SDK) theme={null}
from anyformat.sdk import Client
client = Client(api_key="YOUR_API_KEY")
workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8"
# iter_evals follows next_cursor across pages for you.
for an_eval in client.iter_evals(workflow_id):
print(an_eval.run_number, an_eval.status, an_eval.accuracy)
```
```typescript TypeScript theme={null}
interface EvalSummary {
id: string;
run_number: number;
version_id: string;
status: 'in_progress' | 'processed' | 'error';
accuracy: number | null;
matched: number | null;
mismatched: number | null;
ungraded: number | null;
file_count: number;
failed_count: number;
created_at: string | null;
}
interface EvalPage {
items: EvalSummary[];
next_cursor: string | null;
}
const workflowId = '0686bb97-8c30-70f0-8000-97669e000eb8';
const base = `https://api.anyformat.ai/v3/workflows/${workflowId}/evals/`;
const headers = { 'Authorization': 'Bearer YOUR_API_KEY' };
let cursor: string | null = null;
do {
const url = cursor ? `${base}?cursor=${cursor}` : base;
const response = await fetch(url, { headers });
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const page: EvalPage = await response.json();
for (const e of page.items) {
console.log(e.run_number, e.status, e.accuracy);
}
cursor = page.next_cursor;
} while (cursor);
```
```json Response (200 OK) theme={null}
{
"items": [
{
"id": "069dcc2c-e14c-7606-8000-2ee4fb17b4fa",
"run_number": 4,
"version_id": "abcdef1234",
"status": "in_progress",
"accuracy": null,
"matched": null,
"mismatched": null,
"ungraded": null,
"file_count": 42,
"failed_count": 0,
"created_at": "2026-07-06T09:00:00.000Z"
},
{
"id": "069dcc2c-e14c-7606-8000-2ee4fb17b4f9",
"run_number": 3,
"version_id": "abcdef1234",
"status": "processed",
"accuracy": 0.94,
"matched": 47,
"mismatched": 3,
"ungraded": 1,
"file_count": 42,
"failed_count": 0,
"created_at": "2026-07-05T10:00:00.000Z"
}
],
"next_cursor": null
}
```
## OpenAPI
````yaml GET /v3/workflows/{workflow_id}/evals/
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/workflows/{workflow_id}/evals/:
get:
tags:
- evals
summary: List evals
description: >-
List a workflow's evals, newest first.
Keyset-paginated: follow `next_cursor` until it is `null`. The sort
order is
fixed (`-created_at, -id`); there are no totals or page numbers. Each
item is
the same headline `GET /v3/workflows/{workflow_id}/evals/{eval_id}/`
returns.
An unknown or cross-org workflow returns 404.
operationId: v3_list_evals
parameters:
- name: workflow_id
in: path
required: true
schema:
type: string
title: Workflow Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Page size, capped at 100.
default: 20
title: Limit
description: Page size, capped at 100.
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Opaque token from a previous response's `next_cursor`.
title: Cursor
description: Opaque token from a previous response's `next_cursor`.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EvalListPageV3'
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:
EvalListPageV3:
properties:
items:
items:
$ref: '#/components/schemas/EvalDetailV3'
type: array
title: Items
description: Evals on this page, newest first.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: >-
Opaque token to fetch the next page; pass it back as `?cursor=`.
`null` on the last page.
type: object
required:
- items
title: EvalListPageV3
description: >-
One keyset page of evals.
Fixed ``(-created_at, -id)`` order. No totals or page numbers — iterate
by
following ``next_cursor`` until it is null.
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
EvalDetailV3:
properties:
id:
type: string
title: Id
description: >-
Unique identifier of the eval (hyphenated UUID); equals the launch's
`eval_id`.
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4f9
run_number:
type: integer
title: Run Number
description: 'Per-workflow run counter (#1, #2, …) for this eval.'
examples:
- 3
version_id:
type: string
title: Version Id
description: Workflow version the eval scored.
examples:
- abcdef1234
status:
$ref: '#/components/schemas/EvalStatus'
description: >-
Grading status. Non-terminal: `in_progress`. Terminal: `processed`,
`error`.
examples:
- processed
accuracy:
anyOf:
- type: number
- type: 'null'
title: Accuracy
description: >-
Headline accuracy in [0, 1]; `null` while `in_progress` and on a
`processed` eval with a 0 graded denominator.
examples:
- 0.94
matched:
anyOf:
- type: integer
- type: 'null'
title: Matched
description: Fields that matched ground truth; `null` while `in_progress`.
mismatched:
anyOf:
- type: integer
- type: 'null'
title: Mismatched
description: Fields that mismatched ground truth; `null` while `in_progress`.
ungraded:
anyOf:
- type: integer
- type: 'null'
title: Ungraded
description: >-
Fields with no ground truth to grade against; `null` while
`in_progress`.
file_count:
type: integer
title: File Count
description: Number of dataset documents in the eval's realized cohort.
examples:
- 42
failed_count:
type: integer
title: Failed Count
description: Number of dataset documents that failed to enqueue for this run.
examples:
- 0
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: Timestamp when the eval was created (ISO 8601).
type: object
required:
- id
- run_number
- version_id
- status
- file_count
- failed_count
title: EvalDetailV3
description: >-
One eval's frozen headline — the poll target for a launched run.
``id`` here is the same identifier the launch returned as ``eval_id``.
The
headline fields (``accuracy``, ``matched``, ``mismatched``,
``ungraded``)
are ``null`` while ``status`` is ``in_progress``; ``accuracy`` stays
``null``
on a ``processed`` eval whose graded denominator is 0.
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
EvalStatus:
type: string
enum:
- in_progress
- processed
- error
title: EvalStatus
description: >-
Grading lifecycle of an eval. Non-terminal: ``in_progress`` (the
headline
fields are null). Terminal: ``processed`` (graded) and ``error``.
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/api-key. Send as `Authorization:
Bearer `.
scheme: bearer
````