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

# Get a usage summary



## OpenAPI

````yaml /api-reference/openapi.json get /v1/billing/usage
openapi: 3.1.0
info:
  title: microsandbox cloud API
  description: >-
    REST API for microsandbox cloud: sandbox and volume lifecycle, organization
    context, quotas, usage, and audit events, authenticated with an organization
    API key.
  version: 0.1.0
servers:
  - url: https://api.microsandbox.dev
security:
  - api_key: []
paths:
  /v1/billing/usage:
    get:
      tags:
        - Usage
      summary: Get a usage summary
      operationId: get_usage
      responses:
        '200':
          description: Usage summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummary'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_api_key
                  message: unauthorized
                  details: null
      security:
        - api_key: []
components:
  schemas:
    UsageSummary:
      type: object
      description: Usage summary from the billing provider.
      required:
        - period_start
        - period_end
        - line_items
        - total_cents
      properties:
        daily:
          type: array
          items:
            $ref: '#/components/schemas/UsageDailyPoint'
          description: >-
            Per-day metered quantities for charting. One entry per (day,
            metric).

            Empty when no daily series is available (e.g. provider error).
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/UsageLineItem'
          description: >-
            Period-aggregated breakdown - one entry per billable metric /
            charge.
        period_end:
          type: string
          format: date-time
        period_start:
          type: string
          format: date-time
        projected_spend_cents:
          type: integer
          format: int64
          description: >-
            End-of-period spend projection: `total_cents` linearly extrapolated
            over

            the billing period. Equals `total_cents` when the period can't be

            extrapolated (no future end, or zero elapsed). Never below
            `total_cents`.
        storage_gib:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Current durable-storage usage (GiB) for the org, from the latest
            hourly

            reading. `None` when storage hasn't been sampled (juicefs-ops
            disabled or

            no volumes). Drives the storage allowance bar; cost is in
            `line_items`.
        total_cents:
          type: integer
          format: int64
    ErrorResponse:
      type: object
      description: Error envelope returned by every non-2xx response.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code, e.g. `invalid_api_key`.
            message:
              type: string
              description: Human-readable description of the error.
            details:
              type:
                - object
                - 'null'
              description: Optional structured context for the error.
    UsageDailyPoint:
      type: object
      description: |-
        One day's metered quantity for a single billable metric - the unit of a
        usage time-series chart. Cost is intentionally omitted: invoices are
        period-aggregated, so a per-day dollar figure would have to be derived.
      required:
        - date
        - metric
        - quantity
      properties:
        date:
          type: string
          format: date-time
          description: Start of the day window (UTC).
        metric:
          type: string
          description: Billable-metric name this quantity belongs to.
        quantity:
          type: number
          format: double
    UsageLineItem:
      type: object
      description: A single line item in a usage summary.
      required:
        - name
        - quantity
        - unit
        - amount_cents
      properties:
        amount_cents:
          type: integer
          format: int64
        name:
          type: string
        quantity:
          type: number
          format: double
        unit:
          type: string
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      description: Organization API key (msb_…) - org-scoped programmatic access.

````