> ## Documentation Index > Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get timezone-aware billing usage chart buckets > Returns zero-filled local-calendar buckets for the half-open [start,end) range. `timezone` must be an IANA timezone name (for example, `America/Chicago`). The response is limited to 400 buckets. Every request requires the authenticated team's `billing:read` permission. `billed_total_usd` is gross CPU and memory usage cost before credits, taxes, or payments; storage `cost_usd` is an informational equivalent while storage remains tracked-only and is excluded from that total. ## OpenAPI ````yaml https://raw.githubusercontent.com/superserve-ai/sandbox/refs/heads/main/api/openapi.yaml get /billing/usage-series openapi: 3.1.0 info: title: Superserve API version: 0.1.0 description: > Superserve provides sandbox infrastructure to run AI agents in the cloud. Powered by Firecracker MicroVMs. ## Sandbox lifecycle ``` active <--> paused --> deleted ``` A sandbox is `active` when running and `paused` after being paused. Resuming a paused sandbox returns it to `active`. Deleting releases all resources. | Endpoint | What it does | |----------|-------------| | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) | | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network rules) | | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM | | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it left off | | `DELETE /sandboxes/:id` | Delete sandbox and all resources | ## Sandbox environment By default sandboxes boot from the curated `superserve/base` template (Ubuntu 24.04, 1 vCPU, 1 GB RAM, 4 GB disk, with Python 3.12, Node.js 22, npm, git, curl, and build-essential pre-installed). Callers can override with any template name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned template UUID via the `from_template` field on `POST /sandboxes`. ## Files and commands `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use its `X-Access-Token` (returned by create, resume, and activate), not the team API key. Two host forms reach them: - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id: `. - `https://boxd-{sandbox_id}.sandbox.superserve.ai/...` — no routing header needed. contact: name: Superserve Team license: name: Proprietary servers: - url: https://api.superserve.ai description: Production security: [] paths: /billing/usage-series: get: tags: - Billing summary: Get timezone-aware billing usage chart buckets description: | Returns zero-filled local-calendar buckets for the half-open [start,end) range. `timezone` must be an IANA timezone name (for example, `America/Chicago`). The response is limited to 400 buckets. Every request requires the authenticated team's `billing:read` permission. `billed_total_usd` is gross CPU and memory usage cost before credits, taxes, or payments; storage `cost_usd` is an informational equivalent while storage remains tracked-only and is excluded from that total. operationId: getBillingUsageSeries parameters: - name: start in: query required: true description: Absolute range start (inclusive). schema: type: string format: date-time - name: end in: query required: true description: Absolute range end (exclusive); must be after `start`. schema: type: string format: date-time - name: granularity in: query required: true description: Local calendar bucket size. Weeks start Monday at 00:00. schema: type: string enum: - hour - day - week - month - name: timezone in: query required: true description: IANA timezone used for calendar boundaries and DST rules. schema: type: string example: America/Chicago responses: '200': description: Usage series content: application/json: schema: $ref: '#/components/schemas/BillingUsageSeriesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' '503': description: Pricing is not available for the authenticated team's active plan content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: BillingUsageSeriesResponse: type: object description: Ordered, continuous series of at most 400 timezone-aware buckets. required: - start - end - granularity - timezone - buckets properties: start: type: string format: date-time end: type: string format: date-time granularity: type: string enum: - hour - day - week - month timezone: type: string buckets: type: array items: $ref: '#/components/schemas/BillingUsageSeriesBucket' Error: type: object description: | Error envelope. `error.code` is a stable, machine-readable identifier (e.g. `bad_request`, `not_found`, `conflict`, `rate_limited`, `too_many_builds`, `too_many_templates`, `too_many_sandboxes`, `image_pull_failed`, `step_failed`, `snapshot_failed`, `start_cmd_failed`, `ready_cmd_failed`, `build_failed`). `error.message` is human-readable and may change between releases; clients should branch on `code`, not `message`. properties: error: type: object properties: code: type: string message: type: string BillingUsageSeriesBucket: type: object description: >- A half-open [start,end) absolute interval, clipped at the requested range edges. required: - start - end - cpu - memory - storage - billed_total_usd properties: start: type: string format: date-time end: type: string format: date-time cpu: $ref: '#/components/schemas/BillingUsageSeriesResource' memory: $ref: '#/components/schemas/BillingUsageSeriesResource' storage: $ref: '#/components/schemas/BillingUsageSeriesResource' billed_total_usd: type: number format: double BillingUsageSeriesResource: type: object description: >- Usage and backend-priced cost for one resource in a bucket. Usage units are resource-specific (vCPU-seconds, GiB-seconds, or tracked storage GiB-seconds). required: - usage - cost_usd - tracked - billable properties: usage: type: number format: double cost_usd: type: number format: double tracked: type: boolean billable: type: boolean responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Caller is authenticated but not allowed to perform the action content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: > Rate limit hit — the caller's per-team request budget is temporarily exhausted. Response body uses error code `rate_limited`. Retry after a short backoff; the bucket refills continuously. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: X-API-Key ````