> ## 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 Optimization > Fetch one optimization with its rounds and per-field scores *Rate limit tier: **general**, 600 requests/min. See [Rate limits](https://docs.anyformat.ai/api-reference-v3/introduction.md#rate-limits).* Fetches one [optimization](https://docs.anyformat.ai/guides/health/optimizer.md) by its `id`. It is the poll target for a run started with [`POST /v3/workflows/{workflow_id}/optimizations/`](https://docs.anyformat.ai/api-reference-v3/optimizations/start). The `id` is the identifier that start returned. ## Status model The endpoint **always returns `200` while the optimization exists**. | `status` | Meaning | | - | - | | `evaluating` | Not terminal. The run is scoring a version against the dataset | | `proposing` | Not terminal. The run is writing new descriptions | | `done` | Terminal. `finished_at` is set | | `failed` | Terminal. `error` says why, and `finished_at` is set | Poll until `status` is `done` or `failed`. A run whose worker stopped for more than 100 minutes is reported `failed`. ## Reading the result * `result_version_id` names the workflow version that holds the optimized descriptions. It is `null` until a round is kept. The result goes live as the workflow's latest version. * `baseline_accuracy` and `best_accuracy` are the measured accuracy before the run and the best a round reached. A one-shot run is not measured, so both stay `null`. * `rounds` lists each scored round. Round `0` is the baseline. Each round carries its `matched` and `mismatched` tallies, its `accuracy`, whether it was `accepted`, and `per_field`, the same scores per field, keyed by the field's `persistent_id`. An unknown id returns `404`, and so does an optimization on another workflow or organization: existence never leaks. A caller outside the workflow's organization gets `403`. ```bash curl theme={null} curl -X GET 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/optimizations/069dcc2c-e14c-7606-8000-2ee4fb17b4f9/' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```python Python (SDK) theme={null} import time from anyformat.sdk import Client client = Client(api_key="YOUR_API_KEY") workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8" optimization_id = "069dcc2c-e14c-7606-8000-2ee4fb17b4f9" optimization = client.get_optimization(workflow_id, optimization_id) while optimization.status not in ("done", "failed"): time.sleep(15) optimization = client.get_optimization(workflow_id, optimization_id) print(optimization.status, optimization.best_accuracy, optimization.result_version_id) ``` ```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 optimizationId = '069dcc2c-e14c-7606-8000-2ee4fb17b4f9'; let optimization = await af.getOptimization(workflowId, optimizationId); while (optimization.status !== 'done' && optimization.status !== 'failed') { await new Promise((resolve) => setTimeout(resolve, 15_000)); optimization = await af.getOptimization(workflowId, optimizationId); } console.log(optimization.status, optimization.best_accuracy, optimization.result_version_id); ``` ```json Response (200 OK) theme={null} { "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": [ { "round_no": 0, "version_id": "curr123456", "matched": 5, "mismatched": 5, "accuracy": 0.5, "accepted": false, "note": null, "created_at": "2026-07-05T10:00:00Z", "per_field": [ { "persistent_id": "0686bb978c3070f0800097669e00aaaa", "name": "total", "matched": 5, "mismatched": 5, "accuracy": 0.5 } ] }, { "round_no": 1, "version_id": "abcdef1234", "matched": 8, "mismatched": 2, "accuracy": 0.8, "accepted": true, "note": null, "created_at": "2026-07-05T10:20:00Z", "per_field": [ { "persistent_id": "0686bb978c3070f0800097669e00aaaa", "name": "total", "matched": 8, "mismatched": 2, "accuracy": 0.8 } ] } ], "created_at": "2026-07-05T10:00:00Z", "finished_at": "2026-07-05T10:30:00Z" } ``` ## OpenAPI ````yaml GET /v3/workflows/{workflow_id}/optimizations/{optimization_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-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/{optimization_id}/: get: tags: - optimizations summary: Get optimization description: >- Retrieve one optimization with its rounds and per-field scores. Poll this until `status` is `done` or `failed`. `result_version_id` names the workflow version that holds the optimized descriptions. An unknown optimization, or one on another workflow or organization, returns 404. operationId: v3_get_optimization parameters: - name: workflow_id in: path required: true schema: type: string title: Workflow Id - name: optimization_id in: path required: true schema: type: string title: Optimization Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OptimizationV3' 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: - 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: 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. 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. OptimizationKind: type: string enum: - extraction - extraction_oneshot title: OptimizationKind 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.