> ## 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 usage > Machine time one sandbox consumed and its cost, over its life or a billing window, for per-sandbox billing of your own users. ## OpenAPI ````yaml openapi/boat-v1.yaml GET /sandboxes/{sandboxId}/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}/usage: get: tags: - Boat summary: Get boat usage description: >- Machine time one sandbox consumed, and what it costs, so you can bill your own users per sandbox. Same meter as `GET /limits`: billable seconds with the sandbox type's multiplier applied, paused past a refused stop, never counting time stopped. Narrow it to a billing period with `since` and `until`; a period boundary that falls inside a running stretch splits that stretch pro rata. Works while the sandbox runs and after it stops. operationId: usage parameters: - $ref: '#/components/parameters/SandboxId' - name: since in: query required: false schema: type: string description: >- Count from this time, ISO 8601 or Unix epoch seconds. Default is the sandbox's creation. examples: iso: value: '2026-09-01T00:00:00Z' epoch: value: '1756684800' - name: until in: query required: false schema: type: string description: >- Count up to this time, ISO 8601 or Unix epoch seconds. Default is now. examples: iso: value: '2026-10-01T00:00:00Z' responses: '200': description: Billable machine time for the sandbox inside the window. content: application/json: schema: $ref: '#/components/schemas/SandboxUsageResponse' examples: usage: value: ok: true type: sandbox.usage sandboxId: bx_23456789 sandboxType: default billingMultiplier: 1 since: '2026-09-01T00:00:00.000Z' until: '2026-09-14T09:30:00.000Z' seconds: 4980 dollars: 0.0498 secondsPerDollar: 100000 running: false '400': $ref: '#/components/responses/BadRequest' '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: SandboxUsageResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - sandboxId - sandboxType - billingMultiplier - since - until - seconds - dollars - secondsPerDollar - running properties: type: type: string examples: - sandbox.usage sandboxId: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ examples: - bx_23456789 sandboxType: type: string enum: - small - default - large - xlarge description: >- The sandbox's current machine size, which sets `billingMultiplier`. billingMultiplier: type: number description: >- Rate at which this sandbox consumes machine time. 0.5 for `small`, 1 for `default`, 2 for `large`, and 50/9 for `xlarge`. examples: - 1 since: type: string format: date-time description: >- Start of the window the figures cover. The sandbox's creation time when the request did not pass `since`. until: type: string format: date-time description: >- End of the window. Now when the request did not pass `until`, or passed one in the future. seconds: type: integer description: >- Billable machine-seconds inside the window, the type multiplier already applied: a `large` sandbox that ran ten minutes reads 1200. Includes a running sandbox's time up to `until`. Time while stopped is never counted and time past a refused stop is excluded. examples: - 4980 dollars: type: number description: >- `seconds` at list price (`seconds / secondsPerDollar`), whatever plan, trial or gift actually paid for it. Up to six decimals. examples: - 0.0498 secondsPerDollar: type: integer description: >- How many billable seconds one dollar buys, so you can price `seconds` yourself. examples: - 100000 running: type: boolean description: >- The meter is still moving: the sandbox is up and no refused stop is holding it paused. Read again after it stops for the final figure. `false` on a sandbox that is up but paused past a refused stop, whose figure will not change until it is used again. SuccessBase: type: object required: - ok - type properties: ok: type: boolean examples: - true type: type: string description: Stable success envelope discriminator added by v1. 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: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid: value: ok: false type: sandbox.error status: 400 code: invalid_json message: Request body must be valid JSON. error: code: invalid_json message: Request body must be valid JSON. status: 400 requestId: req_01HX... 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. ````