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

# Get sandbox AI usage

> Proxied AI usage of one sandbox, per day, credential and model.



## OpenAPI

````yaml openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/ai-usage
openapi: 3.1.0
info:
  title: Boat Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    sandboxes from backend services, CI jobs, hosted workers, and Boat
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://boat.dev/api/v1
security:
  - BoatBearerAuth: []
tags:
  - name: Boat
    description: >-
      Unified Boat account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /sandboxes/{sandboxId}/ai-usage:
    get:
      tags:
        - Boat
      summary: Get sandbox AI usage
      description: >-
        One sandbox's proxied AI usage per UTC day, credential and model, and
        whether it is blocked. Needs an API key with `box.read` on the sandbox.
      operationId: getSandboxAiUsage
      parameters:
        - $ref: '#/components/parameters/SandboxId'
        - name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
          description: Days of history, today included.
      responses:
        '200':
          description: The usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxAiUsageResponse'
              examples:
                usage:
                  value:
                    ok: true
                    type: sandbox.ai_usage
                    sandboxId: bx_23456789
                    blocked: false
                    proxied: true
                    credentialProfileId: null
                    since: '2026-09-11'
                    usage:
                      - day: '2026-10-10'
                        credential: claude-subscription
                        model: claude-sonnet-4-5
                        requests: 412
                        errors: 3
                        inputTokens: 51234
                        outputTokens: 80321
                        cacheReadTokens: 1203344
                        cacheWriteTokens: 90233
                    totals:
                      requests: 412
                      errors: 3
                      inputTokens: 51234
                      outputTokens: 80321
                      cacheReadTokens: 1203344
                      cacheWriteTokens: 90233
                    dollars: 0.412
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SandboxId:
      name: sandboxId
      in: path
      required: true
      schema:
        type: string
        pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$
      description: Public Sandbox id returned by create/list/get sandbox calls.
  schemas:
    SandboxAiUsageResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - sandboxId
            - blocked
            - proxied
            - credentialProfileId
            - since
            - usage
            - totals
            - dollars
          properties:
            sandboxId:
              type: string
            blocked:
              type: boolean
              description: True when the proxy refuses this sandbox's placeholders.
            proxied:
              type: boolean
              description: True when the sandbox holds placeholders, not real keys.
            credentialProfileId:
              type:
                - string
                - 'null'
              description: The profile the sandbox uses. Null means its owner's default.
            since:
              type: string
              format: date
            usage:
              type: array
              items:
                $ref: '#/components/schemas/AiUsageRow'
            totals:
              $ref: '#/components/schemas/AiUsageTotals'
            dollars:
              type: number
    SuccessBase:
      type: object
      required:
        - ok
        - type
      properties:
        ok:
          type: boolean
          examples:
            - true
        type:
          type: string
          description: Stable success envelope discriminator added by v1.
    AiUsageRow:
      allOf:
        - type: object
          required:
            - day
            - credential
            - model
          properties:
            day:
              type: string
              format: date
              description: UTC day.
            credential:
              type: string
              description: >-
                The credential used: a `CredentialId`, or `custom:<NAME>` for a
                custom API.
            model:
              type: string
              description: The model the provider reported, or empty.
        - $ref: '#/components/schemas/AiUsageTotals'
    AiUsageTotals:
      type: object
      required:
        - requests
        - errors
        - inputTokens
        - outputTokens
        - cacheReadTokens
        - cacheWriteTokens
      description: Token counts are the numbers the provider reports in its replies.
      properties:
        requests:
          type: integer
        errors:
          type: integer
          description: >-
            Requests the provider answered with an HTTP error, or did not
            answer.
        inputTokens:
          type: integer
        outputTokens:
          type: integer
        cacheReadTokens:
          type: integer
        cacheWriteTokens:
          type: integer
    ErrorEnvelope:
      type: object
      required:
        - ok
        - type
        - status
        - code
        - message
        - error
        - requestId
      properties:
        ok:
          type: boolean
          examples:
            - false
        type:
          type: string
          examples:
            - sandbox.error
        status:
          type: integer
          examples:
            - 409
        code:
          type: string
          examples:
            - provider_not_configured
        message:
          type: string
          examples:
            - Prompting is locked until Codex is configured on the Agents page.
        requestId:
          type: string
          examples:
            - req_01HX...
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            details:
              type: object
              additionalProperties: true
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            unauthorized:
              value:
                ok: false
                type: sandbox.error
                status: 401
                code: unauthorized
                message: Unauthorized
                error:
                  code: unauthorized
                  message: Unauthorized
                  status: 401
                requestId: req_01HX...
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BoatBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sandbox_api_key
      description: >-
        Boat bearer token in the form `boat_...`. Service API keys authenticate
        sandbox operations.

````

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