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

# Query sandbox lifecycle events

> Query a team's sandbox lifecycle events for troubleshooting, auditing and billing reconciliation, filtered by sandbox, template, event type and time range.

Sandbox events provide a queryable timeline of the key sandbox lifecycle operations. Use them for troubleshooting, auditing, usage analysis, and billing reconciliation, from the SDK or from the CLI.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## Query events

The events API lists sandbox events for the team. Events can be filtered by sandbox, template, event type, status, and time range. In the CLI example, `<sandbox-id>` is the sandbox ID.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
event_filter = {
    "sandbox_id": "iq721h44siv24wmyrh5oc",
    "events": "create,pause,resume,connect,timeout,delete",
}

result = ppio.sandbox.get_events(**event_filter, limit=10, offset=0)

print("Events:", result.items)

if result.has_more:
    next_page = ppio.sandbox.get_events(**event_filter, limit=10, offset=10)

    print("Next page:", next_page.items)
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const eventFilter = {
  sandboxID: 'iq721h44siv24wmyrh5oc',
  events: 'create,pause,resume,connect,timeout,delete',
}

const result = await ppio.sandbox.getEvents({
  ...eventFilter,
  limit: 10,
  offset: 0,
})

console.log('Events:', result.items)

if (result.hasMore) {
  const nextPage = await ppio.sandbox.getEvents({
    ...eventFilter,
    limit: 10,
    offset: 10,
  })

  console.log('Next page:', nextPage.items)
}
```

```bash CLI theme={null}
# List events for a sandbox
ppio sandbox events <sandbox-id>

# Filter by event names / state
ppio sandbox events <sandbox-id> --events create,pause,resume --state success
```

> [!WARNING]
>
> `events` is a comma-separated string, not an array. Pass the same filters on every page so that `offset` is applied to the same result set.

## Query events for one sandbox

The events API is at team level. To query events for a sandbox already held, pass its ID as the `sandboxID` / `sandbox_id` filter.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()
result = ppio.sandbox.get_events(
    sandbox_id=sandbox.sandbox_id,
    events="create,pause,resume,connect,timeout,delete",
    limit=10,
)

print(result.items)

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()
const result = await ppio.sandbox.getEvents({
  sandboxID: sandbox.sandboxId,
  events: 'create,pause,resume,connect,timeout,delete',
  limit: 10,
})

console.log(result.items)

await sandbox.kill()
```

## Filter events

> [tab] Python
>
> **start\_time** `int64`
>
> Query start time as a Unix timestamp in seconds. The range is inclusive.
>
> **end\_time** `int64`
>
> Query end time as a Unix timestamp in seconds. Must be greater than `start_time`. Defaults to the current time.
>
> **sandbox\_id** `string`
>
> Filter by sandbox ID. Partial matching is supported.
>
> **template\_id** `string`
>
> Filter by template ID. Partial matching is supported.
>
> **events** `string`
>
> Comma-separated event types. Defaults to the key event set: `create`, `pause`, `resume`, `connect`, `timeout`, `delete`, `auto_pause`, `auto_resume`, and `auto_delete`.
>
> **state** `string`
>
> Filter by event status, such as `success` or a failure status.
>
> **order\_asc** `bool`
>
> Sort events by `recordAt` in ascending order. By default, events are returned in descending order.
>
> **offset** `int32` (default: 0)
>
> Number of events to skip.
>
> **limit** `int32` (default: 10)
>
> Maximum number of events to return.

> [tab] Node.js
>
> **startTime** `number`
>
> Query start time as a Unix timestamp in seconds. The range is inclusive.
>
> **endTime** `number`
>
> Query end time as a Unix timestamp in seconds. Must be greater than `startTime`. Defaults to the current time.
>
> **sandboxID** `string`
>
> Filter by sandbox ID. Partial matching is supported.
>
> **templateID** `string`
>
> Filter by template ID. Partial matching is supported.
>
> **events** `string`
>
> Comma-separated event types. Defaults to the key event set: `create`, `pause`, `resume`, `connect`, `timeout`, `delete`, `auto_pause`, `auto_resume`, and `auto_delete`.
>
> **state** `string`
>
> Filter by event status, such as `success` or a failure status.
>
> **orderAsc** `boolean`
>
> Sort events by `recordAt` in ascending order. By default, events are returned in descending order.
>
> **offset** `number` (default: 0)
>
> Number of events to skip.
>
> **limit** `number` (default: 10)
>
> Maximum number of events to return.

> [!WARNING]
>
> Time fields use Unix timestamps in seconds. Do not pass millisecond timestamps.

## Paginate events

Events use offset-based pagination. Start with `offset` at 0. When `hasMore` is true, request the next page with `offset` plus `limit`.

## Event types

**create** `string`

The sandbox was created.

**pause** `string`

The sandbox was paused by an explicit `pause` call.

**resume** `string`

The sandbox was resumed by an explicit `resume` call.

**connect** `string`

A client connected to the sandbox.

**timeout** `string`

The sandbox timeout or idle timeout expired.

**delete** `string`

The sandbox was deleted by an explicit `kill` call.

**auto\_pause** `string`

The sandbox was paused automatically after a timeout.

**auto\_resume** `string`

A paused sandbox was resumed automatically when activity arrived, such as a `connect` call.

**auto\_delete** `string`

The sandbox was deleted automatically after a timeout.

## Response fields

The response includes an `items` array and pagination metadata.

**items** `object[]`

List of sandbox events that match the query.

**item fields**

**eventID** `string`

Unique event ID.

**recordAt** `number`

Event record time as a Unix timestamp in seconds.

**templateID** `string`

Template ID used by the sandbox.

**templateName** `string`

Template name used by the sandbox.

**sandboxID** `string`

Sandbox ID.

**eventName** `string`

Event type. See [Event types](#event-types) for the full list.

**state** `string`

Event status.

**errorMsg** `string`

Error message when the event failed or encountered an exception. Usually empty when there is no error.

**statusCode** `number`

HTTP status code associated with the operation, when available.

**total** `number`

Total number of events that match the query, before pagination.

**hasMore** `boolean`

Whether more events are available after the current page.


## Related topics

- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)
- [Pause and resume a sandbox](https://docs.ppio.ai/sandbox/pause-resume.md)
- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.