Affinda Usage API
Retrieve daily credits consumption for the organization across all workspaces and document types. Used for billing reconciliation, budget tracking, and FinOps reporting.
OpenAPI Specification
openapi: 3.0.3
info:
title: Affinda Annotations Add x-hidden to endpoints Usage API
version: 3.0.0
description: Affinda Annotations API — subset of the Affinda v3 Document Processing API.
servers:
- url: https://{region}.affinda.com
description: 'Select the correct server for your instance: api (AUS/Global), api.us1 (US), or api.eu1 (EU).'
variables:
region:
default: api
description: The instance region. Use 'api' for AUS/Global, 'api.us1' for US, or 'api.eu1' for EU. You can find your region in the Affinda web app URL.
enum:
- api
- api.eu1
- api.us1
x-ms-parameter-location: client
security:
- ApiKeyAuth: []
tags:
- name: Usage
paths:
/v3/usage:
get:
tags:
- Usage
summary: Get usage
operationId: getUsage
description: 'Returns daily credits consumption for an organization over a date range. Optionally scope the report to a single workspace or document type.
`workspace` and `document_type` cannot be combined: usage data is aggregated independently along each axis, so a per-(workspace × document type) slice is not available.'
parameters:
- in: query
name: organization
required: true
schema:
$ref: '#/components/schemas/Organization_properties-identifier'
description: Organization to report usage for. The caller must be an admin or owner.
- in: query
name: workspace
schema:
$ref: '#/components/schemas/identifier'
description: Optionally scope the report to a single workspace within the organization.
- in: query
name: document_type
schema:
$ref: '#/components/schemas/properties-identifier'
description: Optionally scope the report to a single document type within the organization.
- in: query
name: start
schema:
type: string
format: date
description: Inclusive start date of the report (YYYY-MM-DD). Defaults to 365 days before `end`.
- in: query
name: end
schema:
type: string
format: date
description: Inclusive end date of the report (YYYY-MM-DD). Defaults to today.
responses:
'200':
description: Daily credits consumption for the requested scope.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageResponse'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
components:
schemas:
UsageResponse:
type: object
description: Daily credits consumption for an organization over a date range, optionally scoped to a single workspace or document type.
required:
- scope
- scopeIdentifier
- start
- end
- total
- items
properties:
scope:
type: string
description: What the usage was scoped to.
enum:
- organization
- workspace
- documentType
scopeIdentifier:
type: string
description: Identifier of the scoped entity (organization, workspace, or document type).
start:
type: string
format: date
description: Inclusive start of the reported period (YYYY-MM-DD).
example: '2025-04-01'
end:
type: string
format: date
description: Inclusive end of the reported period (YYYY-MM-DD).
example: '2025-04-30'
total:
type: integer
description: Total credits consumed over the period.
example: 4320
items:
type: array
description: Per-day breakdown. Days with zero usage are omitted.
items:
$ref: '#/components/schemas/UsageItem'
additionalProperties: false
properties-identifier:
type: string
description: Uniquely identify a collection.
example: mEFayXdO
RequestError:
type: object
additionalProperties: false
required:
- type
- errors
properties:
type:
type: string
example: validation_error
errors:
type: array
items:
type: object
required:
- attr
- code
- detail
properties:
attr:
type: string
nullable: true
example: non_field_errors
code:
type: string
example: unique
detail:
type: string
example: This index name has already been used
Organization_properties-identifier:
type: string
description: Uniquely identify an organization.
example: mEFayXdO
UsageItem:
type: object
description: Daily credits consumption for a single date in the requested period.
required:
- date
- count
properties:
date:
type: string
format: date
description: The day this usage was recorded against, in YYYY-MM-DD.
example: '2025-04-15'
count:
type: integer
description: Credits consumed on this day.
example: 123
additionalProperties: false
identifier:
type: string
description: Uniquely identify a workspace.
example: mEFayXdO
responses:
401Error:
description: Authorisation error
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
DefaultError:
description: UnexpectedError
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
400Error:
description: Bad request. If it is a validation error will contain a list of each invalid field
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: 'Basic authentication using an API key, e.g. `{Authorization: Bearer aff_0bb4fbdf97b7e4111ff6c0015471094155f91}`.
You can find your API key within the Settings page of the [Affinda web app](https://app.affinda.com/). You can obtain an API key by [signing up for a free trial](https://app.affinda.com/auth/register).'