---
title: "Explain sandbox status"
method: GET
path: "/orgs/{orgName}/sandboxes/{sandboxName}/status/explain"
tags: ["Sandboxes"]
---

# Explain sandbox status

`GET /orgs/{orgName}/sandboxes/{sandboxName}/status/explain`

## Request

- Base URL: `https://api.signadot.com/api/v2`
- URL: `https://api.signadot.com/api/v2/orgs/{orgName}/sandboxes/{sandboxName}/status/explain`
- Auth: API key in header `signadot-api-key`

Returns a sandbox status explanation. In the default mode (mode=explain), generates a natural-language explanation using an LLM fed with cluster context. When mode=context, returns the assembled LLM messages (system prompt + user context) without calling the LLM. Both modes require the sandbox explain AI feature to be enabled, otherwise they return 403 (the assembled context contains sandbox metadata and is itself sensitive).

## Path parameters

- `orgName` string, required
- `sandboxName` string, required

## Query parameters

- `mode` 'explain' | 'context'

## Response `200`

OK

- SandboxesSandboxStatusExplainResponse
  - `context` SandboxesLLMContext
    - `messages` SandboxesLLMMessage[]
      - `content` string
      - `role` 'system' | 'user'
  - `explanation` string: Explanation is a natural-language explanation of why the sandbox is in its current state and what, if anything, the user can do. Only present when mode=explain.
  - `mode` 'explain' | 'context'
  - `status` SandboxReadiness
    - `connection` SandboxConnectionStatus
      - `devbox` string: Machine to which local mappings in this sandbox may be linked.
      - `session` ConnectSession
        - `createdAt` string
        - `id` string
        - `renewedAt` string
        - `validUntil` string
    - `forwards` SandboxesForwardStatus[]: Forwards status
      - `name` string
      - `tunnel` SandboxTunnelStatus
        - `health` object
          - `connected` boolean
          - `lastCheckTime` string
          - `lastConnectedTime` string
    - `jobs` SandboxesJobsSummary
      - `phaseCounts` JobsPhaseCount[]
        - `count` integer
        - `phase` 'queued' | 'running' | 'failed' | 'succeeded' | 'canceled'
    - `local` SandboxLocalWorkloadStatus[]: Local mappings status
      - `name` string
      - `tunnel` SandboxTunnelStatus
        - `health` object
          - `connected` boolean
          - `lastCheckTime` string
          - `lastConnectedTime` string
    - `message` string: Message is a human readable explanation of why the sandbox is healthy or not.
    - `ready` boolean: Ready indicates whether the sandbox is ready, meaning that it can be used for testing.
    - `reason` string: Reason is a machine readable explanation of why the sandbox is healthy or not.
    - `scheduledDeleteTime` string: ScheduledDeleteTime returns the formatted and computed ttl based on the Duration and OffsetFrom
    - `testExecutions` SandboxTestExecutionsSummary
      - `checks` SandboxTestExecutionsSummaryChecks
        - `failed` integer
        - `passed` integer
      - `phaseCounts` TestexecutionsPhaseCount[]
        - `count` integer
        - `phase` 'pending' | 'in_progress' | 'failed' | 'succeeded' | 'canceled'
      - `trafficDiffs` SandboxTestExecutionsSummaryTrafficDiffs
        - `green` integer
        - `red` integer
        - `yellow` integer

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `501`: Not Implemented
- `502`: Bad Gateway

## Changes

- **2026-06-16** `40d6198d7957`: 1 info
  - added the non-success response with the status `403`
- **2026-05-07** `942b3992433f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/signadot/apis/signadot-api/changes/orgs/:orgName/sandboxes/:sandboxName/status/explain/get.md)

---

[API](https://skmtc.dev/signadot/apis/signadot-api.md) - [All operations](https://skmtc.dev/signadot/apis/signadot-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signadot/apis/signadot-api/revisions/5e80b0f9c718?raw)