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

# Retrieve sandbox usage

> How much sandbox time this session — or the crew under it — has used.



## OpenAPI

````yaml /openapi.json get /v1/sessions/{session_id}/usage
openapi: 3.1.0
info:
  title: Gobare Agent API
  version: v1
  description: >-
    Programmatic access to Gobare coding-agent sessions. Conceptually aligned
    with OpenAI's Agents API; deliberately not wire-compatible with it. See the
    divergence list in the product documentation.
servers:
  - url: https://api.{domain}
    variables:
      domain:
        default: gobare.dev
security: []
paths:
  /v1/sessions/{session_id}/usage:
    get:
      summary: Retrieve sandbox usage
      description: How much sandbox time this session — or the crew under it — has used.
      operationId: get_sessions_session_id_usage
      parameters:
        - name: root
          in: query
          required: false
          schema:
            type: string
          description: >-
            Aggregate the whole tree under this session instead of the one
            session. The id must match the path, which is how a crew total says
            which crew it is.
      responses:
        '200':
          description: >-
            How much sandbox time this session — or the crew under it — has
            used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionUsage'
        '400':
          description: >-
            `invalid_request`. A query parameter this endpoint does not take.
            Refused rather than ignored, because an ignored filter answers with
            everything and looks like a filter that matched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The access token is missing, unrecognised, expired or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The token is valid but may not perform this call. The message names
            the scope it wanted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            No such endpoint, or no such object under this token's organization.
            Another organization's id is indistinguishable from one that never
            existed, deliberately.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            `rate_limit_exceeded`. The token is past its allowance for this
            bucket. Honour `Retry-After`; the `x-ratelimit-*` headers on every
            response say how close you were.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An unexpected error. Quote the request id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - accessToken: []
components:
  schemas:
    SessionUsage:
      type: object
      description: >-
        Sandbox time, split by how settled it is. One number would have to merge
        a live estimate with a reconciled charge and invent a duration for an
        interval nobody can account for, so it is several.
      required:
        - object
        - session_id
        - scope
        - as_of
        - sandbox_seconds
        - chargeable_seconds
        - needs_review_intervals
      properties:
        object:
          type: string
          const: session.usage
        session_id:
          type: string
        scope:
          type: string
          enum:
            - session
            - tree
          description: '`tree` when `?root=` asked for the whole crew.'
        sessions:
          type: integer
          description: How many sessions this total covers.
        as_of:
          type: integer
          description: >-
            Unix ms. A running sandbox is counted up to this moment, so the
            number moves until it stops.
        sandbox_seconds:
          type: integer
          description: >-
            Everything that can be accounted for: settled, pending
            reconciliation, and still running. Not a bill.
        chargeable_seconds:
          type: integer
          description: >-
            The reconciled subset — the part the provider has confirmed. Always
            less than or equal to `sandbox_seconds`.
        needs_review_intervals:
          type: integer
          description: >-
            Intervals whose duration is not known. Reported as a count on
            purpose: inventing seconds for them would make the total look
            settled when it is not.
        intervals:
          type: integer
          description: >-
            How many intervals went into this, excluding ones marked not
            billable at all.
    Error:
      type: object
      required:
        - error
      description: Every refusal this API makes, in one shape.
      properties:
        error:
          description: Always present on a failure, and the only thing present.
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - invalid_request
                - authentication_error
                - permission_denied
                - not_found
                - method_not_allowed
                - conflict
                - queue_full
                - rate_limit_exceeded
                - project_limit_exceeded
                - context_length_exceeded
                - provider_error
                - provider_unauthorized
                - sandbox_error
                - sandbox_unavailable
                - directory_unavailable
                - workspace_recovery_failed
                - bridge_incompatible
                - internal_error
            message:
              type: string
            request_id:
              type: string
              description: >-
                Also on the x-request-id header. Quote it when reporting a
                problem.
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      description: >-
        A `gbr_pat_` access token. Scopes are recorded on the token when it is
        minted.

````