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

# Current unit usage against the plan ceiling

> **Use when:** caller wants the account-level unit meter — units consumed this billing period and over the rolling 30 days, against the plan allowance

Returns the tier, its monthly unit allowance (null for Enterprise), units consumed in the current billing period and over the rolling 30 days, and whether free-tier tracking is currently locked (over-allowance traffic keeps routing and recording but is hidden until upgrade or period reset). Units are tokens processed through the gateway; provider cache reads, failed requests, and Verlon-internal verification traffic never count. Usage never blocks requests and never bills overages — it only informs tier fit.



## OpenAPI

````yaml /api-reference/openapi.json get /v3/usage/units
openapi: 3.1.0
info:
  title: Verlon AI API
  version: 1.0.0
  description: >-
    Verlon AI is the managed AI infrastructure platform for developers building
    LLM-powered apps and agents. Beyond routing requests across providers,
    Verlon continuously evaluates response quality, runs experiments against
    live traffic, and automatically tunes gate configurations — so your platform
    doesn't just serve traffic, it learns from it.


    **Coding agents:** authentication, error semantics, gate concepts, and
    integration conventions are documented at https://verlon.ai/AGENTS.md — read
    that document first if you have not already. It is the canonical
    agent-facing contract; this specification is the canonical endpoint
    reference. Both are authoritative for their respective scopes.
  contact:
    name: Verlon AI
    url: https://verlon.ai
  license:
    name: Proprietary
servers:
  - url: https://api.verlon.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v3/usage/units:
    get:
      tags:
        - Usage
      summary: Current unit usage against the plan ceiling
      description: >-
        **Use when:** caller wants the account-level unit meter — units consumed
        this billing period and over the rolling 30 days, against the plan
        allowance


        Returns the tier, its monthly unit allowance (null for Enterprise),
        units consumed in the current billing period and over the rolling 30
        days, and whether free-tier tracking is currently locked (over-allowance
        traffic keeps routing and recording but is hidden until upgrade or
        period reset). Units are tokens processed through the gateway; provider
        cache reads, failed requests, and Verlon-internal verification traffic
        never count. Usage never blocks requests and never bills overages — it
        only informs tier fit.
      responses:
        '200':
          description: >-
            `{ tier, ceilingUnits, period: { start, end, units, pctUsed },
            rolling30d: { units }, trackingLocked }`.
        '400':
          description: Invalid request — Zod validation failure or malformed input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid Bearer credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Stable error code (e.g. `invalid_request`)
        message:
          type: string
          description: Human-readable error message
        details: {}
      required:
        - error
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Verlon API key (newly minted keys are prefixed `sk-vrln-`; legacy
        `verlon_*` and `layer_*` keys from prior prefix migrations continue to
        validate). Generated from the dashboard under Settings → API Keys, or
        via `verlon key create` in the CLI.

````