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

# Usage and cost

> Metered usage and its cost for a billing period: meters, totals (rated,
not yet rated, credit, due) with a projection for the current month, a
daily breakdown, every template, and the period's sandboxes, most
expensive first, a page at a time.
Dashboard sessions of any role; API keys with the `usage:read` scope.

`sandboxes` holds `limit` rows (50 unless you pass it, at most 1000).
`sandboxCount` is how many sandboxes had usage in the period, on every
page. While more remain the response carries `nextCursor`: pass it back
as `cursor`, with the same `period`, for the next page. A closed
period pages the same way every time; in the current month costs are
still moving, so a sandbox can change pages between requests. To read
one sandbox's row wherever it ranks, pass `sandboxId` instead.

Usage arrives a minute at a time: a minute is included within about 35
seconds of its end, so the minute a sandbox was deleted in shows up
that long after the minute is over, not at the delete. Read again after
that before comparing running time with a sandbox's lifetime.




## OpenAPI

````yaml /api-reference/anona-openapi.yaml get /v1/usage
openapi: 3.0.3
info:
  title: Anona Compute API (Anona routes)
  version: 0.1.0
  description: >
    Routes the Anona Compute gateway serves next to the E2B-compatible API:

    live-view viewer tokens, SSH certificates, network policy, the credential

    vault, usage and billing, webhooks and telemetry export, thumbnails, preview
    links,

    public ports, pause when idle, template builds, and API key management.
servers:
  - url: https://api.compute.anonalabs.com
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Live view
  - name: SSH
  - name: Sandbox access
  - name: Templates
  - name: Network
  - name: Credential vault
  - name: Usage and billing
  - name: Webhooks and telemetry
  - name: API keys
  - name: Service
paths:
  /v1/usage:
    get:
      tags:
        - Usage and billing
      summary: Usage and cost
      description: |
        Metered usage and its cost for a billing period: meters, totals (rated,
        not yet rated, credit, due) with a projection for the current month, a
        daily breakdown, every template, and the period's sandboxes, most
        expensive first, a page at a time.
        Dashboard sessions of any role; API keys with the `usage:read` scope.

        `sandboxes` holds `limit` rows (50 unless you pass it, at most 1000).
        `sandboxCount` is how many sandboxes had usage in the period, on every
        page. While more remain the response carries `nextCursor`: pass it back
        as `cursor`, with the same `period`, for the next page. A closed
        period pages the same way every time; in the current month costs are
        still moving, so a sandbox can change pages between requests. To read
        one sandbox's row wherever it ranks, pass `sandboxId` instead.

        Usage arrives a minute at a time: a minute is included within about 35
        seconds of its end, so the minute a sandbox was deleted in shows up
        that long after the minute is over, not at the delete. Read again after
        that before comparing running time with a sandbox's lifetime.
      operationId: getUsage
      parameters:
        - name: period
          in: query
          schema:
            type: string
            pattern: ^(current|\d{4}-\d{2})$
            default: current
        - name: limit
          in: query
          description: Sandboxes per page.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
        - name: cursor
          in: query
          description: >-
            The `nextCursor` of the previous page, for the same `period`.
            Opaque; a cursor from another period is a 400.
          schema:
            type: string
        - name: sandboxId
          in: query
          description: >-
            Return only this sandbox's row (an empty `sandboxes` if it had no
            usage in the period) instead of a page. Cannot be combined with
            `cursor`.
          schema:
            type: string
            maxLength: 128
      responses:
        '200':
          description: The usage document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          description: The usage service is unavailable; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Usage:
      type: object
      required:
        - tenant
        - period
        - availablePeriods
        - meters
        - totals
        - daily
        - sandboxes
        - sandboxCount
        - templates
      properties:
        tenant:
          $ref: '#/components/schemas/Tenant'
        period:
          type: object
          required:
            - key
            - start
            - end
            - asOf
            - current
          properties:
            key:
              type: string
              example: 2026-10
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
            asOf:
              type: string
              format: date-time
            ratedThrough:
              type: string
              format: date-time
            current:
              type: boolean
        availablePeriods:
          type: array
          items:
            type: string
        meters:
          type: array
          items:
            type: object
            required:
              - meter
              - unit
              - quantity
              - unitPriceUsd
              - amountUsd
            properties:
              meter:
                type: string
                example: vcpu_hours
              unit:
                type: string
              quantity:
                type: number
              unitPriceUsd:
                type: number
              ratedUsd:
                type: number
              pendingUsd:
                type: number
              amountUsd:
                type: number
        totals:
          type: object
          required:
            - ratedUsd
            - pendingUsd
            - amountUsd
            - creditUsd
            - dueUsd
          properties:
            ratedUsd:
              type: number
            pendingUsd:
              type: number
            amountUsd:
              type: number
            creditUsd:
              type: number
            dueUsd:
              type: number
            projectedUsd:
              type: number
        included:
          type: object
          description: >-
            The month against what the plan includes, on the allocated rate card
            (absent for months before the current plans). vCPU-hours each
            include 2 GiB-hours of memory; storage is never included. On this
            rate card `totals.dueUsd` is `overageUsd` for a plan that bills it
            and 0 for Free, which stops instead.
          properties:
            vcpuHours:
              $ref: '#/components/schemas/UsageIncludedLine'
            gibHours:
              $ref: '#/components/schemas/UsageIncludedLine'
            egressGb:
              $ref: '#/components/schemas/UsageIncludedLine'
            storageGibHours:
              $ref: '#/components/schemas/UsageIncludedLine'
            overageUsd:
              type: number
              description: >-
                What is over the included usage at the rate card, storage
                included.
            atLimit:
              type: string
              enum:
                - stop
                - bill
              description: >-
                stop: Free, new sandboxes refused and running ones paused until
                the month ends. bill: paid plans.
            exhausted:
              type: boolean
              description: An included amount is used up.
        daily:
          type: array
          items:
            type: object
        sandboxes:
          type: array
          description: >-
            One page of the period's sandboxes, most expensive first (see
            `limit`, `cursor` and `sandboxId`).
          items:
            $ref: '#/components/schemas/UsageSandbox'
        sandboxCount:
          type: integer
          description: Sandboxes with usage in the period, whatever the page.
        nextCursor:
          type: string
          description: >-
            Pass as `cursor` for the next page. Absent on the last page and for
            a `sandboxId` lookup.
        templates:
          type: array
          description: Every template used in the period, most expensive first.
          items:
            $ref: '#/components/schemas/UsageTemplate'
        lifecycle:
          type: object
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: The HTTP status code.
        message:
          type: string
        error_code:
          type: string
          description: >-
            Machine-readable reason, on some errors (for example
            `invalid_request`).
    Tenant:
      type: object
      required:
        - id
        - slug
        - planId
      properties:
        id:
          type: string
        slug:
          type: string
        name:
          type: string
        planId:
          type: string
        planName:
          type: string
        billingModel:
          type: string
        status:
          type: string
    UsageIncludedLine:
      type: object
      properties:
        used:
          type: number
        included:
          type: number
          description: Absent for storage, which no plan includes.
        over:
          type: number
        unitPriceUsd:
          type: number
        overageUsd:
          type: number
    UsageSandbox:
      type: object
      description: |
        One sandbox's usage in the period. Two kinds of quantity are here and
        they are easy to confuse. **Allocated** quantities are the size the
        sandbox was created at times its running time; from the allocated rate
        card they are what is billed. **Consumed** quantities were
        the billed meters before it, measured
        from the CPU time the sandbox used and the memory it actually held, so
        a 4 vCPU sandbox that sat idle for an hour has `allocatedVcpuHours` 4
        and `vcpuHours` near 0.

        Running time counts from the sandbox's start to its delete (or pause),
        measured from samples every 10 seconds and clipped to the start and
        delete times. It never exceeds that span for a sandbox that was not
        paused, and usually falls short of it by a few seconds at most. After
        a resume it can exceed the true time by up to 10 seconds.
      required:
        - sandboxId
        - template
        - state
        - vcpu
        - memMib
        - runningHours
        - allocatedVcpuHours
        - allocatedGibHours
        - vcpuHours
        - gibHours
        - egressGib
        - snapshotGibHours
        - amountUsd
      properties:
        sandboxId:
          type: string
          description: The sandbox's ID.
        template:
          type: string
          description: >-
            Template name, or the template ID if it has none; `unknown` if the
            sandbox is not in the registry.
        state:
          type: string
          description: >-
            The sandbox's state now: `running`, `paused`, `killed` (deleted),
            and so on.
        vcpu:
          type: integer
          description: Allocated vCPUs, the size it was created at.
        memMib:
          type: integer
          description: Allocated memory in MiB, the size it was created at.
        runningHours:
          type: number
          description: 'Hours it ran in the period: start to delete, minus time paused.'
        allocatedVcpuHours:
          type: number
          description: 'Allocated: `vcpu` x `runningHours`. Not billed.'
        allocatedGibHours:
          type: number
          description: 'Allocated: `memMib` / 1024 x `runningHours`. Not billed.'
        vcpuHours:
          type: number
          description: 'Consumed: CPU time used, in vCPU-hours. Billed.'
        gibHours:
          type: number
          description: 'Consumed: memory actually resident, in GiB-hours. Billed.'
        egressGib:
          type: number
          description: 'Consumed: bytes sent to the internet, in GiB. Billed.'
        snapshotGibHours:
          type: number
          description: 'Consumed: storage its pause snapshots used, in GiB-hours. Billed.'
        amountUsd:
          type: number
          description: >-
            What its usage costs at your plan's rates, in USD; an estimate, not
            an invoice line.
    UsageTemplate:
      type: object
      description: >-
        The sandboxes of one template in the period, summed. Allocated and
        consumed mean what they mean on `UsageSandbox`.
      required:
        - template
        - sandboxes
        - allocatedVcpuHours
        - allocatedGibHours
        - vcpuHours
        - gibHours
        - egressGib
        - amountUsd
      properties:
        template:
          type: string
          description: Template name, or `unknown`.
        sandboxes:
          type: integer
          description: Sandboxes of this template with usage in the period.
        allocatedVcpuHours:
          type: number
          description: >-
            Allocated: the sum of its sandboxes' size x running time, in
            vCPU-hours. Not billed.
        allocatedGibHours:
          type: number
          description: 'Allocated: the same in GiB-hours. Not billed.'
        vcpuHours:
          type: number
          description: 'Consumed: CPU time used, in vCPU-hours. Billed.'
        gibHours:
          type: number
          description: 'Consumed: memory actually resident, in GiB-hours. Billed.'
        egressGib:
          type: number
          description: 'Consumed: bytes sent to the internet, in GiB. Billed.'
        amountUsd:
          type: number
          description: >-
            What its sandboxes' usage costs at your plan's rates, in USD; an
            estimate.
  responses:
    BadRequest:
      description: The request body is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No valid API key or session.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key's scopes or the caller's role do not allow this.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        An Anona Compute API key (`ac_` followed by lowercase hex; older keys
        start with `e2b_`).
    BearerAuth:
      type: http
      scheme: bearer
      description: 'The same API key, sent as `Authorization: Bearer ac_...`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.