> ## 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 Workflow Runs
> List all runs for a workflow with pagination
Each run corresponds to one file collection, identified by UUID.
## Query Parameters
| Parameter | Type | Default | Description |
| ----------- | ------- | ------- | ----------------------------------------- |
| `page` | integer | `1` | Page number (minimum: 1) |
| `page_size` | integer | `20` | Items per page (minimum: 1, maximum: 100) |
```bash curl theme={null}
curl -X GET 'https://api.anyformat.ai/v2/workflows/550e8400-e29b-41d4-a716-446655440000/runs/?page=1&page_size=20' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
```python Python (requests) theme={null}
import requests
workflow_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://api.anyformat.ai/v2/workflows/{workflow_id}/runs/"
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
params = {"page": 1, "page_size": 20}
response = requests.get(url, headers=headers, params=params)
print(response.json())
```
```javascript JavaScript theme={null}
const workflowId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://api.anyformat.ai/v2/workflows/${workflowId}/runs/?page=1&page_size=20`,
{
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
console.log(data);
```
```typescript TypeScript theme={null}
interface WorkflowRun {
id: string;
status: string;
created_at: string | null;
updated_at: string | null;
}
interface WorkflowRunListResponse {
results: WorkflowRun[];
count: number;
page: number;
page_size: number;
}
const workflowId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://api.anyformat.ai/v2/workflows/${workflowId}/runs/?page=1&page_size=20`,
{
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const data: WorkflowRunListResponse = await response.json();
console.log(data.results);
```
```json Response (200 OK) theme={null}
{
"count": 42,
"page": 1,
"page_size": 20,
"results": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "processed",
"created_at": "2024-03-24T12:00:00.000Z",
"updated_at": "2024-03-24T12:02:30.000Z"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "in_progress",
"created_at": "2024-03-24T13:00:00.000Z",
"updated_at": "2024-03-24T13:00:15.000Z"
}
]
}
```
## OpenAPI
````yaml GET /v2/workflows/{workflow_id}/runs/
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
1. **Create a workflow** in the [AnyFormat
dashboard](https://app.anyformat.ai) and define the fields you want to
extract.
2. **Run the workflow** via `POST /v2/workflows/{workflow_id}/run/` with a
file attached.
3. **Fetch results** via `GET
/v2/workflows/{workflow_id}/files/{collection_id}/results/` once processing
completes.
## Authentication
All endpoints (except `/health/`) require a Bearer token in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from
[app.anyformat.ai/settings](https://app.anyformat.ai/settings).
## Versioning
All endpoints use the `/v2/` path prefix. All responses include
`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: webhooks
description: >-
Webhook subscriptions for asynchronous event notifications. Get notified
when extractions complete or fail.
- name: health
description: Health check endpoints to verify API availability.
paths:
/v2/workflows/{workflow_id}/runs/:
get:
tags:
- workflows
summary: List workflow runs
description: >-
List all extraction runs for a workflow with pagination.
Each run corresponds to a file collection that was processed by the
workflow.
Use the run's `id` (collection UUID) with
`GET /v2/workflows/{workflow_id}/files/{id}/results/` to fetch detailed
results.
operationId: v2_list_workflow_runs
parameters:
- name: workflow_id
in: path
required: true
schema:
type: string
title: Workflow Id
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
title: Page
- name: page_size
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 20
title: Page Size
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- ApiKeyAuth: []
components:
schemas:
WorkflowRunListResponse:
properties:
results:
items:
$ref: '#/components/schemas/WorkflowRunListItem'
type: array
title: Results
description: List of runs for the current page.
count:
type: integer
title: Count
description: Total number of runs for this workflow.
examples:
- 3
page:
type: integer
title: Page
description: Current page number.
examples:
- 1
page_size:
type: integer
title: Page Size
description: Number of results per page.
examples:
- 20
type: object
required:
- results
- count
- page
- page_size
title: WorkflowRunListResponse
description: Paginated list of workflow runs.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
WorkflowRunListItem:
properties:
id:
type: string
title: Id
description: >-
The collection UUID for this run. Use this ID with `GET
/v2/workflows/{workflow_id}/files/{id}/results/` to fetch results.
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4e1
status:
type: string
title: Status
description: >-
Processing status: `pending`, `queued`, `in_progress`, `processed`,
`error`, or `cancelled`.
examples:
- processed
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: Timestamp when the run started (ISO 8601).
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
description: Timestamp when the run status was last updated (ISO 8601).
type: object
required:
- id
- status
title: WorkflowRunListItem
description: >-
An extraction run entry, representing one execution of a workflow on a
file collection.
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
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/settings. Send as `Authorization:
Bearer `.
scheme: bearer
````