> ## 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 Optimizations > List a workflow's optimizations, newest first *Rate limit tier: **general**, 600 requests/min. See [Rate limits](https://docs.anyformat.ai/api-reference-v3/introduction.md#rate-limits).* Returns one keyset page of a workflow's [optimizations](https://docs.anyformat.ai/guides/health/optimizer.md), newest first. Follow `next_cursor` until it is `null`. See [Pagination](https://docs.anyformat.ai/api-reference-v3/introduction.md#pagination). Pass `kind` to keep one kind: `extraction` for measured runs, `extraction_oneshot` for one-shot runs. Omit it to list both. An unknown `kind` returns `400 VALIDATION_ERROR`. Each item has the shape [`GET …/optimizations/{optimization_id}/`](https://docs.anyformat.ai/api-reference-v3/optimizations/get) returns, except that every round leaves `per_field` empty. Read one optimization by id for its per-field scores. The newest item is the workflow's latest optimization, so there is no separate route for it. An unknown workflow returns `404`, as does one in another organization. ```bash curl theme={null} curl -X GET 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/optimizations/?kind=extraction&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" page = client.list_optimizations(workflow_id, kind="extraction", limit=20) for optimization in page.items: print(optimization.id, optimization.status, optimization.best_accuracy) ``` ```typescript TypeScript theme={null} import { Anyformat } from '@anyformat/sdk'; const af = new Anyformat({ apiKey: 'YOUR_API_KEY' }); const workflowId = '0686bb97-8c30-70f0-8000-97669e000eb8'; const page = await af.listOptimizations(workflowId, { kind: 'extraction', limit: 20 }); for (const optimization of page.items) { console.log(optimization.id, optimization.status, optimization.best_accuracy); } ``` ```json Response (200 OK) theme={null} { "items": [ { "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4f9", "workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8", "kind": "extraction", "status": "done", "max_rounds": 3, "baseline_accuracy": 0.5, "best_accuracy": 0.8, "result_version_id": "abcdef1234", "error": null, "rounds": [], "created_at": "2026-07-05T10:00:00Z", "finished_at": "2026-07-05T10:30:00Z" } ], "next_cursor": null } ``` ## OpenAPI ````yaml GET /v3/workflows/{workflow_id}/optimizations/ 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: webhooks description: >- Webhooks — an HTTPS endpoint of yours that hears of every run's ending, signed per the Standard Webhooks specification, instead of polling the run. - 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/workflows/{workflow_id}/optimizations/: get: tags: - optimizations summary: List optimizations description: >- List a workflow's optimizations, newest first. Keyset-paginated: follow `next_cursor` until it is `null`. There are no totals or page numbers. Items leave `per_field` empty in every round: read one optimization by id for the per-field scores. An unknown or cross-org workflow returns 404. operationId: v3_list_optimizations parameters: - name: workflow_id in: path required: true schema: type: string title: Workflow Id - name: kind in: query required: false schema: anyOf: - $ref: '#/components/schemas/OptimizationKind' - type: 'null' description: Only optimizations of this kind. title: Kind description: Only optimizations of this kind. - 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/OptimizationListPageV3' 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_ERROR` — The request failed validation. `detail` is a list of `{type, loc, msg}`, one per failure; `loc[0]` is the request part. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: VALIDATION_ERROR: value: error: The request failed validation. detail: - type: missing loc: - body - name msg: Field required error_code: VALIDATION_ERROR retryable: false request_id: req_abc123 recovery: >- Read `detail` for what failed validation, correct the request, and send it again. '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 recovery: >- Check that the key is complete and has not been revoked, or create a new key. 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 recovery: >- Send your API key in the `Authorization: Bearer ` header. '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 recovery: >- Use an API key from the organization that owns this resource, or ask one of its admins for access. 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 recovery: >- Create an API key with the scope `params.required_scope` names, and use it for this call. '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 recovery: >- Check the ID, and that it belongs to your API key's organization; `params.resource_type` names what is missing. '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 recovery: >- Wait the seconds the `Retry-After` header gives, or back off exponentially without one, then retry. '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 recovery: >- Retry with exponential backoff, and contact support with the `request_id` if it keeps failing. '502': description: >- A backend service broke the connection before it answered, or 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 recovery: >- Retry with exponential backoff, and contact support with the `request_id` if it keeps failing. '503': description: >- A backend service could not be reached or is unavailable (`SERVICE_UNAVAILABLE`). Retry with backoff when `retryable` is true. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: SERVICE_UNAVAILABLE: value: error: The service is temporarily unavailable. detail: The service is temporarily unavailable. error_code: SERVICE_UNAVAILABLE retryable: true request_id: req_abc123 recovery: Retry the request with exponential backoff. '504': description: >- A backend service did not answer in time. Retry with backoff when `retryable` is true. 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 recovery: Retry the request with exponential backoff. security: - ApiKeyAuth: [] components: schemas: OptimizationKind: type: string enum: - extraction - extraction_oneshot title: OptimizationKind OptimizationListPageV3: properties: items: items: $ref: '#/components/schemas/OptimizationV3' type: array title: Items description: Optimizations 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: OptimizationListPageV3 description: One keyset page of optimizations, newest first. 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 `{type, loc, msg}` objects for `VALIDATION_ERROR`, whose `loc` starts with `body`, `query`, `path`, `header`, `form` or `tool`, and an object for a structured error such as `FILENAME_CONFLICT` (`detail.conflicts`). error_code: type: string enum: - ACCESS_DENIED - AUTH_FAILED - CONCURRENT_EDIT - CONFLICT - DATASET_DOCUMENT_REJECTED - DATASET_GROUND_TRUTH_SAVE_FAILED - DATASET_INVALID_REQUEST - DATASET_UNSUPPORTED - EMPTY_EVAL - ENDPOINT_RETIRED - EXTRACT_MODE_FORBIDDEN - EXTRACT_NODE_UNRESOLVED - FILENAME_CONFLICT - FILE_TOO_LARGE - GATEWAY_TIMEOUT - GONE - 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 - MULTIFILE_UNSUPPORTED - NOT_ACCEPTABLE - NOT_ASSIGNED_VERIFIER - NOT_FOUND - NOT_IMPLEMENTED - NOT_IN_DATASET - OBJECT_STORAGE_UNAVAILABLE - ONESHOT_SIGNALS_MISSING - OPERATOR_DEPRECATED - OPERATOR_NOT_AVAILABLE - OPTIMIZATION_ALREADY_RUNNING - PARSE_MODE_FORBIDDEN - PAYMENT_REQUIRED - PRECONDITION_FAILED - RATE_LIMITED - REPARSE_REQUIRED - REQUEST_REJECTED - REQUEST_TOO_LARGE - RUN_IN_PROGRESS - SERVICE_UNAVAILABLE - SPLIT_HAS_NO_PAGES - SPLIT_SOURCE_NOT_PDF - TOPOLOGY_INVALID - UNSUPPORTED_FILE_TYPE - UNSUPPORTED_LOOKUP_FILE - UNSUPPORTED_MEDIA_TYPE - UPLOAD_SNIFF_BUDGET_EXCEEDED - URL_UNREACHABLE - VALIDATION_ERROR - WEBHOOK_SUBSCRIPTION_LIMIT - 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`. recovery: type: string description: >- One sentence that says what to do next. Absent when the `error_code` has none, or when `retryable` differs from the code's usual value. OptimizationV3: properties: id: type: string title: Id description: Unique identifier of the optimization (hyphenated UUID). examples: - 069dcc2c-e14c-7606-8000-2ee4fb17b4f9 workflow_id: type: string title: Workflow Id description: The optimized workflow (hyphenated UUID). kind: $ref: '#/components/schemas/OptimizationKind' status: $ref: '#/components/schemas/OptimizationStatus' max_rounds: type: integer title: Max Rounds description: Most rounds the run may try. baseline_accuracy: anyOf: - type: number - type: 'null' title: Baseline Accuracy description: >- Accuracy before any change; `null` until scored and on a one-shot run. best_accuracy: anyOf: - type: number - type: 'null' title: Best Accuracy description: >- Best accuracy any round reached; `null` until scored and on a one-shot run. result_version_id: anyOf: - type: string - type: 'null' title: Result Version Id description: >- The workflow version that holds the optimized descriptions; `null` until a round is kept. error: anyOf: - type: string - type: 'null' title: Error description: Why the run failed; `null` unless `status` is `failed`. rounds: items: $ref: '#/components/schemas/OptimizationRoundV3' type: array title: Rounds created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: When the run started (ISO 8601). finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At description: >- When the run reached `done` or `failed` (ISO 8601); `null` while it runs. type: object required: - id - workflow_id - kind - status - max_rounds - rounds title: OptimizationV3 description: One optimization run. OptimizationStatus: type: string enum: - evaluating - proposing - done - failed title: OptimizationStatus description: >- Lifecycle of a run. Non-terminal: `evaluating`, `proposing`. Terminal: `done`, `failed`. OptimizationRoundV3: properties: round_no: type: integer title: Round No description: 0 is the baseline; rounds that propose a change count from 1. version_id: anyOf: - type: string - type: 'null' title: Version Id description: Workflow version the round scored; `null` before it is minted. matched: type: integer title: Matched description: Values that matched ground truth. mismatched: type: integer title: Mismatched description: Values that did not match ground truth. accuracy: type: number title: Accuracy description: Round accuracy in [0, 1]. accepted: type: boolean title: Accepted description: Whether the round's change was kept. note: anyOf: - type: string - type: 'null' title: Note description: Why the round was kept or dropped. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: When the round was recorded (ISO 8601). per_field: items: $ref: '#/components/schemas/OptimizationFieldScoreV3' type: array title: Per Field description: >- Scores per field. Empty on a list item: read the optimization by id for them. type: object required: - round_no - matched - mismatched - accuracy - accepted - per_field title: OptimizationRoundV3 OptimizationFieldScoreV3: properties: persistent_id: type: string title: Persistent Id description: The field's `persistent_id` in the workflow schema. name: anyOf: - type: string - type: 'null' title: Name description: The field's name in the round's version. matched: type: integer title: Matched description: Values of this field that matched ground truth. mismatched: type: integer title: Mismatched description: Values of this field that did not match ground truth. accuracy: type: number title: Accuracy description: '`matched / (matched + mismatched)`, 0 when nothing was graded.' type: object required: - persistent_id - matched - mismatched - accuracy title: OptimizationFieldScoreV3 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.