Skip to main content
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.
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 and Install and authenticate.

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

Filter events

int64
Query start time as a Unix timestamp in seconds. The range is inclusive.
int64
Query end time as a Unix timestamp in seconds. Must be greater than start_time. Defaults to the current time.
string
Filter by sandbox ID. Partial matching is supported.
string
Filter by template ID. Partial matching is supported.
string
Comma-separated event types. Defaults to the key event set: create, pause, resume, connect, timeout, delete, auto_pause, auto_resume, and auto_delete.
string
Filter by event status, such as success or a failure status.
bool
Sort events by recordAt in ascending order. By default, events are returned in descending order.
int32
default:"0"
Number of events to skip.
int32
default:"10"
Maximum number of events to return.
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

string
The sandbox was created.
string
The sandbox was paused by an explicit pause call.
string
The sandbox was resumed by an explicit resume call.
string
A client connected to the sandbox.
string
The sandbox timeout or idle timeout expired.
string
The sandbox was deleted by an explicit kill call.
string
The sandbox was paused automatically after a timeout.
string
A paused sandbox was resumed automatically when activity arrived, such as a connect call.
string
The sandbox was deleted automatically after a timeout.

Response fields

The response includes an items array and pagination metadata.
object[]
List of sandbox events that match the query.
number
Total number of events that match the query, before pagination.
boolean
Whether more events are available after the current page.
Last modified on November 19, 2026