# Show when each Sandbox was running, paused or lost over a time window, with how many ran at once.

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

GET

/v1/sandboxes/timeline

Select code samplecURL (shell:curl)

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


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

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

* Production APIapp.everruns.com/api/v1/sandboxes/timeline

## Parameters

### Query Parameters

**state**

string

Comma-separated states: `running`, `paused`, `lost`, `starting`, `failed`, `not_started`, `deleted`, or `live` for the first five.

**provider**

string

Comma-separated provider ids, such as `daytona,modal`.

**agent\_id**

string

Only Sandboxes of Sessions that ran this Agent.

**sandbox\_template\_id**

string

Only Sandboxes created from this Sandbox Template.

**needs\_attention**

boolean

Only Sandboxes with at least one attention reason.

**search**

string

Case-insensitive match on Session title, Agent, provider or provider resource id.

**include\_in\_process**

boolean

Include in-process targets (virtual filesystem, host), which have no provider resource.

**from**

string format: date-time

Window start (RFC 3339). Defaults to 24 hours before `to`.

**to**

string format: date-time

Window end (RFC 3339). Defaults to now.

**limit**

integer format: int64

Lanes to return, 1 to 200. Defaults to 50.

## Responses

### 200

Success

Media typeapplication/json

Lifecycle of the fleet over a window.

object

**concurrency**

required

Step series of concurrently running Sandboxes across every lane.

Array\<object>

How many Sandboxes were running from `at` until the next point.

object

**at**

required

string format: date-time

**running**

required

integer format: int64

**from**

required

string format: date-time

**lanes**

required

Lanes ordered by running time, longest first.

Array\<object>

One Sandbox’s lane on the timeline.

object

**running\_seconds**

required

Seconds spent running within the window.

integer format: int64

**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

**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

**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

**spans**

required

Spans clipped to the window, oldest first.

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

**peak\_at**

string | null format: date-time

**peak\_running**

required

integer format: int64

**to**

required

string format: date-time

**total\_lanes**

required

Sandboxes with activity in the window, including those beyond `limit`.

integer format: int64

##### Example

```json
{
  "lanes": [
    {
      "sandbox": {
        "agent_name": "Coder",
        "checkpoint_count": 12,
        "desired_state": "ready",
        "external_id": "dtn-7f3a91c2",
        "generation": 1,
        "id": "sandbox_01933b5a00007000800000000000001",
        "idle_after_seconds": 300,
        "provider": "daytona",
        "role": "primary",
        "session_title": "Fix flaky CI",
        "state": "running",
        "target_kind": "managed",
        "template": {
          "display_name": "Coding - Daytona",
          "id": "sbxtpl_01933b5a00007000800000000000001",
          "revision": 4
        },
        "workspace_path": "/home/daytona/workspace"
      },
      "spans": [
        {
          "state": "running"
        }
      ]
    }
  ]
}
```