Skip to main content
ppio.sandbox.list() returns the sandboxes a team owns. Listing is how a program learns a sandbox ID that another process created, and it takes filters so a large set narrows on the server. Once a running sandbox is found, connect to it with ppio.sandbox.connect().
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.

List sandboxes

Filter by metadata

Filter sandboxes with metadata key-value pairs. Specifying multiple key-value pairs returns sandboxes that match all of them. The filtering is performed on the server, which keeps a large set of sandboxes manageable.

Filter by state

The state filter accepts running, paused, or both, and returns the sandboxes in those states.

Page through results

ppio.sandbox.list() returns a paginator. next_items() / nextItems() returns one page of sandboxes, running and paused.

Set the page size

For finer control over pagination, pass the number of items to return per page with limit, and pass nextToken or next_token to start from a known position.

Retrieve all pages

To retrieve all pages, iterate the paginator. has_next / hasNext is initially true before the first page is fetched and becomes false after the last page is returned.

List options

SandboxQuery
Filter conditions.
int
Number of items to return per page. Optional.
string
Position where pagination starts. Optional.

Paginator fields

method
List[SandboxInfo]
Returns one page of sandboxes, running and paused.
bool
True before the first page is fetched, and False after the last page is returned.
Optional[str]
Position where the next page starts.
Last modified on November 19, 2026