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

# Get session sandbox status

> Returns the current lifecycle and runtime state for the sandbox bound to a session. The chat UI polls this endpoint while showing the "loading sandbox…" state and flips to "ready" when `status` becomes `active`. The response includes `lifecycleVersion` (an optimistic concurrency token) and a `lifecycle` envelope with `serverTime`, the lifecycle FSM `state`, and timestamps for last activity, hibernation deadline, and sandbox expiry. As a side effect, if the runtime state is stale (expired or overdue for hibernation), the lifecycle workflow is kicked to clean up — callers do not need to do this themselves.



## OpenAPI

````yaml GET /api/sandbox/status
openapi: 3.1.0
info:
  title: Recoup API - Session Sandboxes
  description: >-
    Per-session sandbox lifecycle for agent runs. These endpoints provision,
    restore, and report status on the Sandbox bound to a single agent session.
    Distinct from the legacy `/api/sandboxes` (plural) account-scoped endpoints
    — these are session-scoped and used by the open-agents-style chat UI to
    drive the "loading sandbox…" state on session entry.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /api/sandbox/status:
    get:
      summary: Get session sandbox status
      description: >-
        Returns the current lifecycle and runtime state for the sandbox bound to
        a session. The chat UI polls this endpoint while showing the "loading
        sandbox…" state and flips to "ready" when `status` becomes `active`. The
        response includes `lifecycleVersion` (an optimistic concurrency token)
        and a `lifecycle` envelope with `serverTime`, the lifecycle FSM `state`,
        and timestamps for last activity, hibernation deadline, and sandbox
        expiry. As a side effect, if the runtime state is stale (expired or
        overdue for hibernation), the lifecycle workflow is kicked to clean up —
        callers do not need to do this themselves.
      parameters:
        - name: sessionId
          in: query
          required: true
          description: The id of the session whose sandbox status to read.
          schema:
            type: string
      responses:
        '200':
          description: Sandbox status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxStatusResponse'
        '400':
          description: Missing `sessionId` query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — invalid or missing API key / Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — the authenticated account does not own this session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found — no session exists with the given `sessionId`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SandboxStatusResponse:
      type: object
      required:
        - status
        - hasSnapshot
        - lifecycleVersion
        - lifecycle
      properties:
        status:
          type: string
          enum:
            - active
            - no_sandbox
          description: >-
            `active` when a non-expired sandbox is bound to the session;
            `no_sandbox` otherwise. The chat UI flips out of its loading state
            when this becomes `active`.
        hasSnapshot:
          type: boolean
          description: >-
            True when a paused/snapshotted sandbox exists and can be resumed.
            Used by the UI to decide whether to show "resume" vs "create"
            affordances when `status` is `no_sandbox`.
        lifecycleVersion:
          type: integer
          description: >-
            Optimistic concurrency token for lifecycle transitions. Clients can
            pass this back to lifecycle-mutating endpoints to detect races.
        lifecycle:
          $ref: '#/components/schemas/SandboxLifecycle'
    Error:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - error
          description: Always `"error"` for error responses.
        error:
          type: string
          description: Human-readable error message.
    SandboxLifecycle:
      type: object
      required:
        - serverTime
        - state
        - lastActivityAt
        - hibernateAfter
        - sandboxExpiresAt
      description: >-
        Lifecycle envelope shared between `GET /api/sandbox/status` and `GET
        /api/sandbox/reconnect`. Server-clock-stamped snapshot of the sandbox's
        lifecycle FSM state and the timestamps the UI uses to render countdown
        timers.
      properties:
        serverTime:
          type: integer
          format: int64
          description: >-
            Server's current epoch milliseconds. Use this — not the client clock
            — when computing how much time is left before `hibernateAfter` or
            `sandboxExpiresAt`.
        state:
          type: string
          nullable: true
          enum:
            - provisioning
            - active
            - hibernating
            - hibernated
            - restoring
            - archived
            - failed
          description: >-
            Lifecycle FSM state. `null` for sessions that have never had a
            sandbox.
        lastActivityAt:
          type: integer
          format: int64
          nullable: true
          description: >-
            Epoch milliseconds of the last recorded sandbox activity, or null if
            there has been none.
        hibernateAfter:
          type: integer
          format: int64
          nullable: true
          description: >-
            Epoch milliseconds after which the sandbox is eligible for
            hibernation, or null when not applicable.
        sandboxExpiresAt:
          type: integer
          format: int64
          nullable: true
          description: >-
            Epoch milliseconds when the sandbox runtime expires, or null when
            not applicable.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer

````