# List the decisions behind a Sandbox's states

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

[Docs](https://everruns.com/docs/)/[API reference](https://everruns.com/docs/api/)/[Operations & billing](https://everruns.com/docs/api/groups/operations-billing/)/List the decisions behind a Sandbox's states

# List the decisions behind a Sandbox's states

Preview

List why a Sandbox changed state, or did not: each pause, resume and delete by the idle timer, idle sweep, retention sweep or a person, each decision to skip, and each failure, beside the state history.

Public APIEverruns Cloud and self-hosted Platform

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

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

## Parameters

### Path Parameters

**id**

required

string

Prefixed public identifier

### Query Parameters

**from**

string format: date-time

Window start (RFC 3339). Defaults to the Sandbox’s creation.

**to**

string format: date-time

Window end (RFC 3339). Defaults to now.

**limit**

integer format: int64

Most events, 1 to 500 (the newest when there are more). Defaults to 200.

## Responses

200Success

### 200

Success

Media typeapplication/json

A Sandbox’s decisions and states over a window.

object

**events**

required

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

**from**

required

string format: date-time

**sandbox_id**

required

string

**states**

required

States over the same window, oldest first. A state change with no event beside it was made by an agent’s sandbox call or found on the provider (a lost sandbox), not by a lifecycle decision.

Array\<object>

A span of time a Sandbox spent in one state.

object

**current**

required

The Sandbox is still in this state.

boolean

**end**

required

string format: date-time

**generation**

required

Incarnation during the span.

integer format: int64

**start**

required

string format: date-time

**state**

required

Fleet state during the span.

string

**to**

required

string format: date-time

### Example

```json
{
  "events": [
    {
      "action": "pause",
      "actor": "idle_sweep",
      "outcome": "skipped",
      "reason": "session_active"
    }
  ],
  "states": [
    {
      "state": "running"
    }
  ]
}
```

404Sandbox not found

### 404

Sandbox not found

FetchcURL

Request

```js
const url = 'https://app.everruns.com/api/v1/sandboxes/example/events';
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/events
```

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

200404

200 · Success

```json
{
  "events": [
    {
      "action": "pause",
      "actor": "idle_sweep",
      "at": "2026-10-12T09:00:00Z",
      "detail": {},
      "generation": 0,
      "message": "string",
      "outcome": "skipped",
      "reason": "session_active"
    }
  ],
  "from": "2026-10-12T09:00:00Z",
  "sandbox_id": "string",
  "states": [
    {
      "current": true,
      "end": "2026-10-12T09:00:00Z",
      "generation": 0,
      "start": "2026-10-12T09:00:00Z",
      "state": "running"
    }
  ],
  "to": "2026-10-12T09:00:00Z"
}
```

404 · Sandbox not found

No response body example is declared for this status.

## Matching endpoints