Affinda Usage API

openapi: 3.2.0
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:
    Organization_properties-identifier:
      type: string
      description: Uniquely identify an organization.
      example: mEFayXdO
    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
                - 'null'
                example: non_field_errors
              code:
                type: string
                example: unique
              detail:
                type: string
                example: This index name has already been used
    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
    identifier:
      type: string
      description: Uniquely identify a workspace.
      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
  responses:
    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
    DefaultError:
      description: UnexpectedError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
    401Error:
      description: Authorisation error
      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).'