# Explain why a Sandbox is in its state

Source: <https://everruns.com/docs/api/operations/diagnose_sandbox/>

[Docs](https://everruns.com/docs/)/[API reference](https://everruns.com/docs/api/)/[Operations & billing](https://everruns.com/docs/api/groups/operations-billing/)/Explain why a Sandbox is in its state

# Explain why a Sandbox is in its state

Preview

Explain why a Sandbox is in its state: its record against what the provider reports, the pinned lifecycle policy and its deadlines, whether its session is running or stuck in a turn, the latest lifecycle decisions and failures, as findings with what to do. Deterministic. The provider is asked only for organization admins.

Public APIEverruns Cloud and self-hosted Platform

GET`/v1/sandboxes/{id}/diagnosis`

See [authentication](https://everruns.com/docs/sre/runbooks/authentication/) for credentials and permissions.

## Parameters

### Path Parameters

**id**

required

string

Prefixed public identifier

## Responses

200Success

### 200

Success

Media typeapplication/json

Everything known about why a Sandbox is in its state.

object

**findings**

required

Problems and warnings first.

Array\<object>

One finding: what is true, why it matters, how to fix it.

object

**fix**

string | null

**id**

required

Stable identifier, such as `provider.state` or `lifecycle.overdue`.

string

**status**

required

How a check came out. Ordered from best to worst so the report’s verdict is the maximum.

string

Allowed values: ok info warning problem

**summary**

required

string

**title**

required

string

**why**

string | null

**generated_at**

required

string format: date-time

**lifecycle**

One of:

* object

  The lifecycle policy pinned when the Session was created, and what it means for this Sandbox now.

  object

  **delete_after_seconds**

  How long a paused Sandbox is kept before deletion; `null` keeps it.

  integer | null format: int64

  **delete_due_at**

  When the retention sweep deletes the provider sandbox (paused only).

  string | null format: date-time

  **idle_action**

  required

  `checkpoint_and_stop`, `stop`, `keep_running` or `delete`.

  string

  **idle_after_seconds**

  required

  Inactivity before the idle action.

  integer format: int64

  **idle_since**

  required

  Last activity, from which every deadline counts.

  string format: date-time

  **pause_due_at**

  When the in-process idle timer pauses it (running only).

  string | null format: date-time

  **stale_turn_pause_at**

  When the sweep pauses it although its session claims a running turn.

  string | null format: date-time

  **sweep_pause_at**

  When the sweep pauses it if the timer did not (running only).

  string | null format: date-time

* null

  null

**provider**

One of:

* object

  What the provider says now; absent when it was not asked.

  object

  **active**

  Whether it holds compute (and so bills for it), when known.

  boolean | null

  **auto_archive_minutes**

  integer | null format: int64

  **auto_delete_minutes**

  integer | null format: int64

  **auto_stop_minutes**

  The provider’s own idle stop in minutes (0 is off). It acts on its own, independently of Everruns’ idle pause.

  integer | null format: int64

  **checked_at**

  required

  string format: date-time

  **created_at**

  string | null format: date-time

  **desired_state**

  string | null

  **details**

  required

  Size, region, image and similar non-secret details.

  object

  **_key_**

  additional properties

  string

  **ends_at**

  When the provider ends the sandbox on its own.

  string | null format: date-time

  **error**

  The provider’s own error or exit reason.

  string | null

  **exists**

  required

  Whether the provider still knows the sandbox.

  boolean

  **external_id**

  required

  string

  **labels**

  required

  Labels Everruns set on it.

  object

  **_key_**

  additional properties

  string

  **last_activity_at**

  string | null format: date-time

  **provider**

  required

  string

  **recoverable**

  boolean | null

  **state**

  required

  Provider-native state, such as `started`, `stopped` or `archived`.

  string

  **updated_at**

  string | null format: date-time

* null

  null

**provider_note**

Why the provider was not asked, or what went wrong asking it.

string | null

**recent_events**

required

The latest recorded causes, oldest first.

Array\<object>

One recorded cause: who acted on the Sandbox (or decided not to), and why.

object

**action**

required

`pause`, `resume` or `delete`.

string

**actor**

required

`idle_timer`, `idle_sweep`, `retention_sweep` or `person`.

string

**at**

required

string format: date-time

**detail**

required

object

**generation**

required

Incarnation the event applied to.

integer format: int64

**message**

required

What happened, in one sentence.

string

**outcome**

required

`done`, `skipped` or `failed`.

string

**reason**

required

Stable reason code, such as `idle_limit`, `stale_turn`, `session_active`, `idle_pause_off`, `retention`, `idle_action_delete` or `provider_error`.

string

**sandbox**

required

One logical Sandbox in the organization.

object

**agent_id**

Agent the Session ran.

string | null

**agent_name**

Agent display name.

string | null

**attention**

required

Why this Sandbox needs attention: `lost`, `failed`, `init_failed`, `idle_running` (running with no activity for an hour) or `cleanup_failed`.

Array\<string>

**checkpoint_count**

required

Committed workspace checkpoints.

integer format: int64

**created_at**

required

string format: date-time

**deleted_at**

string | null format: date-time

**desired_state**

required

Lifecycle intent the control plane is moving the Sandbox toward: `ready`, `paused` or `deleted`.

string

**external_id**

Provider’s id for the latest physical resource.

string | null

**generation**

required

Incarnation counter. Above 1 means the provider resource was lost and rebuilt.

integer format: int64

**id**

required

Durable logical Sandbox id. Stays the same when the provider resource is replaced.

string

**idle_after_seconds**

Inactivity interval before the Sandbox is paused.

integer | null format: int64

**image**

Image the template asked for (`target.options.image`), when it named one.

string | null

**last_activity_at**

Last recorded tool activity or state change.

string | null format: date-time

**last_init_error**

Error from the latest init commands, if they failed.

string | null

**provider**

required

Provider id, such as `daytona`, `modal` or `docker`.

string

**role**

required

`primary` (addressed implicitly by shell and file tools) or `resource`.

string

**session_id**

Owning Session; absent once the Session is deleted.

string | null

**session_title**

Session title, kept after the Session is deleted.

string | null

**size**

Size the template asked for (`target.options.size`), when it named one.

string | null

**state**

required

`running`, `paused`, `lost`, `starting`, `failed`, `not_started` or `deleted`.

string

**target_kind**

Target kind from the pinned specification: `managed`, `container`, `machine`, `vfs` or `host`.

string | null

**template**

One of:

* object

  Template revision the Sandbox was created from.

  object

  **display_name**

  Template display name.

  string | null

  **id**

  required

  Sandbox Template id.

  string

  **revision**

  Revision number pinned when the Session was created.

  integer | null format: int32

* null

  null

**updated_at**

required

string format: date-time

**workspace_path**

Working directory inside the Sandbox.

string | null

**shard_sandbox**

The sandbox as its shard records it (v2 sessions).

object | null

**status**

required

The worst status of any finding.

string

Allowed values: ok info warning problem

**work**

required

The session’s work, as the runtime sees it.

object

**attempts**

integer | null format: int32

**cancel_requested_at**

string | null format: date-time

**claim_expires_at**

string | null format: date-time

**claimed**

Whether a worker holds the turn right now.

boolean | null

**data_plane**

required

The session runs on a v2 data plane (a shard).

boolean

**pending_inputs**

Inputs admitted but not yet taken by a turn.

integer | null format: int64

**phase**

Where the turn is: `idle`, `queued`, `running`, …

string | null

**phase_since**

string | null format: date-time

**queued_since**

Waiting for a worker since.

string | null format: date-time

**session_status**

`active` means a turn is running.

string | null

### Example

```json
{
  "findings": [
    {
      "id": "provider.auto_stop",
      "status": "ok"
    }
  ],
  "lifecycle": {
    "idle_action": "checkpoint_and_stop"
  },
  "provider": {
    "provider": "daytona",
    "state": "stopped"
  },
  "recent_events": [
    {
      "action": "pause",
      "actor": "idle_sweep",
      "outcome": "skipped",
      "reason": "session_active"
    }
  ],
  "sandbox": {
    "agent_name": "Coder",
    "checkpoint_count": 12,
    "desired_state": "ready",
    "external_id": "dtn-7f3a91c2",
    "generation": 1,
    "id": "sandbox_01933b5a00007000800000000000001",
    "idle_after_seconds": 300,
    "image": "ghcr.io/everruns/sandbox-dev:v0.53.0",
    "provider": "daytona",
    "role": "primary",
    "session_title": "Fix flaky CI",
    "size": "small",
    "state": "running",
    "target_kind": "managed",
    "template": {
      "display_name": "Coding - Daytona",
      "id": "sbxtpl_01933b5a00007000800000000000001",
      "revision": 4
    },
    "workspace_path": "/home/daytona/workspace"
  },
  "status": "ok"
}
```

404Sandbox not found

### 404

Sandbox not found

FetchcURL

Request

```js
const url = 'https://app.everruns.com/api/v1/sandboxes/example/diagnosis';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

Request

```sh
curl --request GET \
  --url https://app.everruns.com/api/v1/sandboxes/example/diagnosis
```

Additional language examples require JavaScript. The default request example is available above.

200404

200 · Success

```json
{
  "findings": [
    {
      "id": "provider.auto_stop",
      "status": "ok",
      "summary": "string",
      "title": "string"
    }
  ],
  "generated_at": "2026-10-12T09:00:00Z",
  "recent_events": [
    {
      "action": "pause",
      "actor": "idle_sweep",
      "at": "2026-10-12T09:00:00Z",
      "detail": {},
      "generation": 0,
      "message": "string",
      "outcome": "skipped",
      "reason": "session_active"
    }
  ],
  "sandbox": {
    "agent_name": "Coder",
    "attention": [
      "string"
    ],
    "checkpoint_count": 12,
    "created_at": "2026-10-12T09:00:00Z",
    "desired_state": "ready",
    "external_id": "dtn-7f3a91c2",
    "generation": 1,
    "id": "sandbox_01933b5a00007000800000000000001",
    "idle_after_seconds": 300,
    "image": "ghcr.io/everruns/sandbox-dev:v0.53.0",
    "provider": "daytona",
    "role": "primary",
    "session_title": "Fix flaky CI",
    "size": "small",
    "state": "running",
    "target_kind": "managed",
    "updated_at": "2026-10-12T09:00:00Z",
    "workspace_path": "/home/daytona/workspace"
  },
  "status": "ok",
  "work": {
    "data_plane": true
  }
}
```

404 · Sandbox not found

No response body example is declared for this status.

## Matching endpoints