> ## 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 quota usage



## OpenAPI

````yaml /api-reference/openapi.json get /v1/quotas
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/quotas:
    get:
      tags:
        - Quotas
      summary: Get quota usage
      operationId: get_quotas
      responses:
        '200':
          description: Quota usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaUsage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_api_key
                  message: unauthorized
                  details: null
        '404':
          description: Org not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: org_not_found
                  message: org not found
                  details: null
      security:
        - api_key: []
components:
  schemas:
    QuotaUsage:
      allOf:
        - $ref: '#/components/schemas/PoolUsage'
        - type: object
          required:
            - pool_exhausted
            - total_sandboxes
            - concurrent_ephemeral_running
            - concurrent_persistent_running
            - is_suspended
          properties:
            concurrent_ephemeral_running:
              type: integer
              format: int64
              description: Currently running/starting ephemeral sandboxes.
            concurrent_persistent_running:
              type: integer
              format: int64
              description: Currently running/starting persistent sandboxes.
            included_disk_gib_hours:
              type:
                - integer
                - 'null'
              format: int32
              description: >-
                Included writable-disk GiB-hours/month (display/billing only -
                never a wall).
            included_storage_gib:
              type:
                - integer
                - 'null'
              format: int32
              description: Included durable-storage GiB/month.
            is_suspended:
              type: boolean
              description: >-
                Whether sandbox usage has been manually suspended for the
                organization.
            max_concurrent_ephemeral_running:
              type:
                - integer
                - 'null'
              format: int32
              description: Maximum simultaneously-running ephemeral sandboxes.
            max_concurrent_persistent_running:
              type:
                - integer
                - 'null'
              format: int32
              description: Maximum simultaneously-running persistent sandboxes.
            max_disk_size_mib_per_sandbox:
              type:
                - integer
                - 'null'
              format: int32
              description: Maximum writable disk size (MiB) per sandbox.
            max_memory_mib_per_sandbox:
              type:
                - integer
                - 'null'
              format: int32
              description: Maximum memory (MiB) per sandbox.
            max_sandboxes:
              type:
                - integer
                - 'null'
              format: int32
              description: Maximum total sandboxes the org can have.
            max_total_storage_gib:
              type:
                - integer
                - 'null'
              format: int32
              description: Per-org durable-storage hard cap (GiB).
            max_uptime_minutes_per_sandbox:
              type:
                - integer
                - 'null'
              format: int32
              description: Maximum uptime per sandbox (minutes), if set.
            max_vcpus_per_sandbox:
              type:
                - integer
                - 'null'
              format: int32
              description: Maximum CPU cores per sandbox.
            pool_exhausted:
              type: boolean
              description: >-
                Snapshot of [`PoolUsage::pool_exhausted`] at read time, for API

                consumers - true when this org's sandboxes are being stopped and
                starts

                refused.
            total_sandboxes:
              type: integer
              format: int64
              description: Total sandboxes (all states) for the org.
      description: >-
        Resolved quota limits and current usage for an organization.


        Limits are resolved via COALESCE: per-org override > plan. Every limit
        is

        `Option`: `None` = unlimited (counts/budgets) or the system/node max

        (per-sandbox vcpu/memory/disk). There is no magic 0.
    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.
    PoolUsage:
      type: object
      description: >-
        An org's monthly pool usage against its hard-cap pools - the shared home
        of

        the exhaustion predicates, whether read per-org (embedded in
        `QuotaUsage`)

        or in the quota monitor's batched sweep (`OrgPoolUsage`).
      required:
        - hard_cap
        - vcpu_hours_used
        - memory_gib_hours_used
      properties:
        hard_cap:
          type: boolean
          description: >-
            Whether the plan hard-stops at its included pools (no overflow).

            DERIVED (not a stored column): true iff the resolved plan is
            unpriced -

            an unpriced plan has no overage path, so its pools become walls.
        included_memory_gib_hours:
          type:
            - integer
            - 'null'
          format: int32
          description: Included memory GiB-hours/month; `None` = unlimited.
        included_vcpu_hours:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Included vCPU-hours/month; `None` = unlimited. On `hard_cap` plans
            this

            is the compute wall; on priced plans, usage beyond it is metered
            overage.
        memory_gib_hours_used:
          type: number
          format: double
          description: >-
            Memory GiB-hours consumed this billing month (compute-on-read from
            `sandbox_runs`).
        vcpu_hours_used:
          type: number
          format: double
          description: >-
            vCPU-hours consumed this billing month (compute-on-read from
            `sandbox_runs`).
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      description: Organization API key (msb_…) - org-scoped programmatic access.

````