> ## Documentation Index > Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get box usage > Machine time one box consumed and its cost, over its life or a billing window, for per-box billing of your own users. ## OpenAPI ````yaml openapi/box-v1.yaml GET /boxes/{boxId}/usage openapi: 3.1.0 info: title: Box Public API v1 version: 1.0.0 description: > Public JSON API for creating, operating, prompting, observing, and exposing Box sandboxes from backend services, CI jobs, hosted workers, and Box automation products. The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. servers: - url: https://ascii.dev/api/box/v1 security: - BoxBearerAuth: [] tags: - name: Box description: >- Unified Box account, setup, lifecycle, prompting, event history, desktop access, and SSH operations. paths: /boxes/{boxId}/usage: get: tags: - Box summary: Get box usage description: >- Machine time one box consumed, and what it costs, so you can bill your own users per box. Same meter as `GET /limits`: billable seconds with the box 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 box runs and after it stops. operationId: usage parameters: - $ref: '#/components/parameters/BoxId' - name: since in: query required: false schema: type: string description: >- Count from this time, ISO 8601 or Unix epoch seconds. Default is the box'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 box inside the window. content: application/json: schema: $ref: '#/components/schemas/BoxUsageResponse' examples: usage: value: ok: true type: box.usage boxId: bx_23456789 boxType: 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: BoxId: name: boxId in: path required: true schema: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ description: Public Box id returned by create/list/get box calls. schemas: BoxUsageResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - boxId - boxType - billingMultiplier - since - until - seconds - dollars - secondsPerDollar - running properties: type: type: string examples: - box.usage boxId: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ examples: - bx_23456789 boxType: type: string enum: - small - default - large - xlarge description: The box's current machine size, which sets `billingMultiplier`. billingMultiplier: type: number description: >- Rate at which this box 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 box'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` box that ran ten minutes reads 1200. Includes a running box'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 box is up and no refused stop is holding it paused. Read again after it stops for the final figure. `false` on a box 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: - box.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: box.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: box.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: BoxBearerAuth: type: http scheme: bearer bearerFormat: box_api_key description: >- Box bearer token in the form `box_...`. Service API keys authenticate Box operations. ````