> ## 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 Workflow Usage > The pages and credits a workflow's document runs were billed for over a range of days *Rate limit tier: **general**, 600 requests/min. See [Rate limits](https://docs.anyformat.ai/api-reference-v3/introduction.md#rate-limits).* Returns what a workflow's document runs processed: `pages` and `credits` are what those runs were billed for, and `error_pages` are the pages of its runs that ended in error. The numbers are the workflow's row on the usage page. See [Usage & Billing](https://docs.anyformat.ai/concepts/usage-and-billing.md). Credits a workflow spends without a document are not counted here: [knowledge asks](https://docs.anyformat.ai/api-reference-v3/knowledge/ask.md), optimization proposals and edit-reference parses. They are on the invoice, so `credits` can be lower than the invoice's total for the workflow. ## Pick the days `date_from` and `date_to` are days as `YYYY-MM-DD` in UTC, and both ends are included. Omit both for the workflow's whole history, or one of them for an open range. A `date_from` after `date_to` answers `400` with `error_code: VALIDATION_ERROR`. A charge counts on the day it was made, not on the day its document was uploaded. A document run again on a later day is billed again, and that charge lands on the later day. A deleted document still counts, because its charge stays on the invoice. An error page counts on the day its run started. To count the pages of the documents uploaded on given days instead, add up `usage.pages` over [List workflow runs](https://docs.anyformat.ai/api-reference-v3/runs/list.md) filtered by upload day. An unknown workflow, or one that belongs to another organization, answers `404` with `error_code: NOT_FOUND`. ```bash curl theme={null} curl -X GET 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/usage/?date_from=2026-10-01&date_to=2026-10-31' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```python Python (requests) theme={null} import requests workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8" url = f"https://api.anyformat.ai/v3/workflows/{workflow_id}/usage/" headers = {"Authorization": "Bearer YOUR_API_KEY"} usage = requests.get(url, headers=headers, params={"date_from": "2026-10-01", "date_to": "2026-10-31"}).json() print(usage["pages"], usage["error_pages"], usage["credits"]) ``` ```python Python (SDK) theme={null} from datetime import date from anyformat.sdk import Client client = Client(api_key="YOUR_API_KEY") usage = client.get_workflow_usage( "0686bb97-8c30-70f0-8000-97669e000eb8", date_from=date(2026, 10, 1), date_to=date(2026, 10, 31) ) print(usage.pages, usage.error_pages, usage.credits) ``` ```typescript TypeScript (SDK) theme={null} import { Anyformat } from "@anyformat/sdk"; const af = new Anyformat({ apiKey: "YOUR_API_KEY" }); const usage = await af.getWorkflowUsage("0686bb97-8c30-70f0-8000-97669e000eb8", { dateFrom: "2026-10-01", dateTo: "2026-10-31", }); console.log(usage.pages, usage.error_pages, usage.credits); ``` ```json Response (200 OK) theme={null} { "pages": 1240, "error_pages": 12, "credits": 37200 } ``` ```json Response (404 Not Found) theme={null} { "error": "Resource not found", "detail": "Workflow not found", "error_code": "NOT_FOUND", "retryable": false, "request_id": "a1b2c3d4e5f67890abcdef1234567890" } ``` ## OpenAPI ````yaml GET /v3/workflows/{workflow_id}/usage/ 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}/usage/: get: tags: - workflows summary: Get workflow usage description: >- The pages and credits a workflow's document runs were billed for, and the pages of its failed runs. The numbers are the workflow's row on the usage page. Credits spent without a document (knowledge asks, optimization proposals and edit-reference parses) are not counted. A charge counts on the day it was made, so a document run again on a later day counts again on that day; a deleted document still counts. Omit both dates for the workflow's whole history. operationId: v3_get_workflow_usage parameters: - name: workflow_id in: path required: true schema: type: string title: Workflow Id - name: date_from in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: >- First day to count, inclusive, as `YYYY-MM-DD` in UTC. Omit to count from the start. examples: - '2026-10-01' title: Date From description: >- First day to count, inclusive, as `YYYY-MM-DD` in UTC. Omit to count from the start. - name: date_to in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: >- Last day to count, inclusive, as `YYYY-MM-DD` in UTC. Omit to count up to now. examples: - '2026-10-31' title: Date To description: >- Last day to count, inclusive, as `YYYY-MM-DD` in UTC. Omit to count up to now. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WorkflowUsageV3' 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: WorkflowUsageV3: properties: pages: type: integer title: Pages description: >- The pages the workflow's document runs billed, over the charges made on those days. error_pages: type: integer title: Error Pages description: >- The pages of the runs that ended in error, over the runs started on those days. credits: type: integer title: Credits description: >- The credits the workflow's document runs spent, over the charges made on those days. type: object required: - pages - error_pages - credits title: WorkflowUsageV3 description: >- What a workflow's document runs processed: the workflow's row on the usage page. Credits spent without a document (knowledge asks, optimization proposals and edit-reference parses) are not counted. 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. 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.