> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# get_usage

> Aggregate job units for a billing period. Cost class: fast.

Denominated in the same cost units the front door admits work with — a
caller that is rate-limited and a caller reading its bill must see the same
number, or one of the two is a fiction.

``pages`` and ``bytes_ingested`` aggregate the per-job processing volume
the workers record at completion time.



## OpenAPI

````yaml /openapi.json get /v1/usage
openapi: 3.1.0
info:
  description: >-
    Document intelligence: parse, split, classify, extract, and ground files, or
    build a searchable workspace. Authenticate with ``X-API-Key``.
  title: NDI Platform API
  version: 0.1.0
servers:
  - url: https://ndi-api.nace.ai
security: []
tags: []
paths:
  /v1/usage:
    get:
      tags:
        - operations
      summary: get_usage
      description: >-
        Aggregate job units for a billing period. Cost class: fast.


        Denominated in the same cost units the front door admits work with — a

        caller that is rate-limited and a caller reading its bill must see the
        same

        number, or one of the two is a fiction.


        ``pages`` and ``bytes_ingested`` aggregate the per-job processing volume

        the workers record at completion time.
      operationId: get_usage_v1_usage_get
      parameters:
        - description: Start of the billing window, inclusive.
          in: query
          name: period_start
          required: true
          schema:
            description: Start of the billing window, inclusive.
            format: date
            title: Period Start
            type: string
        - description: End of the billing window, inclusive.
          in: query
          name: period_end
          required: true
          schema:
            description: End of the billing window, inclusive.
            format: date
            title: Period End
            type: string
        - description: >-
            Restrict to one workspace.  Omit to aggregate all jobs for this API
            key.
          in: query
          name: workspace_id
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: >-
              Restrict to one workspace.  Omit to aggregate all jobs for this
              API key.
            title: Workspace Id
        - description: 'Aggregation key: calendar day, job kind, or workspace.'
          in: query
          name: group_by
          required: false
          schema:
            default: day
            description: 'Aggregation key: calendar day, job kind, or workspace.'
            enum:
              - day
              - kind
              - workspace
            title: Group By
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ndi_service__app__platform_api__operations__schemas__UsageResponse
          description: Successful Response
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Gateway Timeout
        default:
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  detail: null
                  message: >-
                    Request body has extra fields that this operation does not
                    accept.
                  request_id: req-01j9k2n3p4q5r6s7t8v9
                  retryable: false
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: >-
            Typed error envelope used by every 4xx and 5xx. ``error.code``
            distinguishes the failure; HTTP status is a consequence of the code.
      security:
        - APIKeyHeader: []
components:
  schemas:
    ndi_service__app__platform_api__operations__schemas__UsageResponse:
      additionalProperties: false
      description: >-
        Usage report covering ``[period_start, period_end]``.


        ``units_total`` is the sum of all bucket units for the period so a
        caller

        can read its budget consumption without summing the page itself.
      properties:
        buckets:
          items:
            $ref: '#/components/schemas/UsageBucket'
          title: Buckets
          type: array
        group_by:
          title: Group By
          type: string
        period_end:
          format: date
          title: Period End
          type: string
        period_start:
          format: date
          title: Period Start
          type: string
        units_total:
          title: Units Total
          type: integer
      required:
        - period_start
        - period_end
        - group_by
        - buckets
        - units_total
      title: UsageResponse
      type: object
    ErrorEnvelope:
      description: Every non-2xx body on ``/v1``.
      example:
        error:
          code: invalid_request
          detail: null
          message: Request body has extra fields that this operation does not accept.
          request_id: req-01j9k2n3p4q5r6s7t8v9
          retryable: false
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
      title: ErrorEnvelope
      type: object
    UsageBucket:
      additionalProperties: false
      description: >-
        One aggregation bucket returned by ``GET /usage``.


        Denominated in the same cost units the front door admits work with — a

        caller that is rate-limited and a caller reading its bill must see the
        same

        number, or one of the two is a fiction.
      properties:
        bytes_ingested:
          title: Bytes Ingested
          type: integer
        jobs:
          title: Jobs
          type: integer
        key:
          title: Key
          type: string
        pages:
          title: Pages
          type: integer
        units:
          title: Units
          type: integer
      required:
        - key
        - units
        - jobs
        - pages
        - bytes_ingested
      title: UsageBucket
      type: object
    Error:
      description: The error object, per spec 12 §1.8.
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Structured payload, when the code carries one.
          title: Detail
        message:
          description: Human- and model-readable; says what to do differently.
          title: Message
          type: string
        request_id:
          description: Per-request correlation id; matches the ``X-Request-Id`` header.
          title: Request Id
          type: string
        retryable:
          description: Whether retrying the identical request could succeed.
          title: Retryable
          type: boolean
      required:
        - code
        - message
        - retryable
        - request_id
      title: Error
      type: object
    ErrorCode:
      description: |-
        Every error the ``/v1`` surface can return.

        Clients must treat this as an **open** enum: a new member is an additive
        change (spec 12 §9), and a client that crashes on an unknown code makes
        every future error a breaking change.
      enum:
        - invalid_request
        - unsupported_file_type
        - file_too_large
        - invalid_schema
        - invalid_sql
        - invalid_path_prefix
        - command_not_permitted
        - batch_too_large
        - domain_validation_failed
        - default_label_required
        - wait_required_for_zero_retention
        - workspace_not_found
        - file_not_found
        - job_not_found
        - upload_not_found
        - node_not_found
        - schema_not_found
        - domain_not_found
        - session_not_found
        - access_label_not_found
        - path_conflict
        - schema_version_conflict
        - access_label_name_taken
        - workspace_name_taken
        - access_label_in_use
        - upload_expired
        - file_not_ingested
        - workspace_deleting
        - workspace_not_deletable
        - ingestion_in_progress
        - job_not_cancellable
        - confirmation_required
        - domain_not_published
        - domain_in_use
        - reserved_domain_slug
        - kg_not_built
        - kg_build_in_progress
        - session_busy
        - range_not_satisfiable
        - result_expired
        - access_denied
        - access_backstop_violation
        - access_mode_not_implemented
        - rate_limited
        - concurrency_limit_reached
        - quota_exceeded
        - corrupt_file
        - zero_byte_file
        - encrypted_file
        - parse_failed
        - ocr_failed
        - conversion_failed
        - sheetless_workbook
        - unplayable_media
        - unclassified_pages
        - job_cancelled
        - job_timeout
        - upstream_unavailable
        - internal_error
        - unauthorized
        - not_implemented
      title: ErrorCode
      type: string
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````