List Sandboxes

List and filter active sandboxes with pagination support.

Method Signatures

Sandbox.list(
    limit: Optional[int] = None,
    cursor: Optional[str] = None,
    since: Optional[int] = None,
    until: Optional[int] = None,
    internet_access: Optional[bool] = None,
    min_exec_count: Optional[int] = None,
    max_exec_count: Optional[int] = None,
    metadata_exists: Optional[list[str]] = None,
    metadata_equals: Optional[dict[str, str]] = None
) -> List[Sandbox]

Sandbox.list_page(
    limit: int = 100,
    cursor: Optional[str] = None,
    since: Optional[int] = None,
    until: Optional[int] = None,
    internet_access: Optional[bool] = None,
    min_exec_count: Optional[int] = None,
    max_exec_count: Optional[int] = None,
    metadata_exists: Optional[list[str]] = None,
    metadata_equals: Optional[dict[str, str]] = None
) -> Dict[str, Any]

Sandbox.list() automatically paginates through all pages when limit is not provided.

Use Sandbox.list_page() for manual cursor-based pagination with full control.

Parameters

limitintoptional

Maximum sandboxes to return. Defaults to None (fetches all) for list(), or 100 for list_page().

cursorstroptional

Pagination cursor from previous response. Use with limit for manual pagination.

sinceintoptional

Unix timestamp (epoch seconds). Only return sandboxes created at or after this time.

untilintoptional

Unix timestamp (epoch seconds). Only return sandboxes created before this time.

internet_accessbooloptional

Filter by internet access. True for sandboxes with internet, False for isolated sandboxes.

min_exec_countintoptional

Minimum number of executions. Only return sandboxes with at least this many commands executed.

max_exec_countintoptional

Maximum number of executions. Only return sandboxes with at most this many commands executed.

metadata_existslist[str]optional

List of metadata keys that must exist. Returns only sandboxes that have all specified keys. Uses AND semantics (all keys must be present).

metadata_equalsdict[str, str]optional

Dictionary of key-value pairs that must match exactly. Returns only sandboxes where all specified metadata matches. Uses AND semantics (all pairs must match).

Returns

Sandbox.list()

Returns List[Sandbox] sorted by creation time (newest first). Auto-paginates when no limit specified.

Sandbox.list_page()

Returns a Dict[str, Any] with the following keys:

sandboxesList of Sandbox instances

countNumber of sandboxes in this page

has_moreBoolean indicating if more pages exist

next_cursorCursor for fetching next page (or None)

Examples

Basic Usage

from concave import Sandbox

# List all sandboxes (auto-paginates)
sandboxes = Sandbox.list()
print(f"Total: {len(sandboxes)} sandboxes")

for sbx in sandboxes:
    print(f"ID: {sbx.id}")

Manual Pagination

from concave import Sandbox

# Get first page
page1 = Sandbox.list_page(limit=50)
print(f"Page 1: {page1['count']} sandboxes")
print(f"Has more: {page1['has_more']}")

# Get next page if available
if page1['has_more']:
    page2 = Sandbox.list_page(
        limit=50, 
        cursor=page1['next_cursor']
    )
    print(f"Page 2: {page2['count']} sandboxes")

Time Filtering

from concave import Sandbox
import time

# Get sandboxes from last hour
one_hour_ago = int(time.time()) - 3600
recent = Sandbox.list(since=one_hour_ago)
print(f"Last hour: {len(recent)} sandboxes")

# Get sandboxes in specific time range
start = int(time.time()) - 86400  # 24h ago
end = int(time.time()) - 3600     # 1h ago
older = Sandbox.list(since=start, until=end)
print(f"Between 24h-1h ago: {len(older)}")

Filter by Internet Access

from concave import Sandbox

# Get sandboxes with internet
connected = Sandbox.list(internet_access=True)
print(f"With internet: {len(connected)}")

# Get isolated sandboxes
isolated = Sandbox.list(internet_access=False)
print(f"Isolated: {len(isolated)}")

Filter by Metadata

from concave import Sandbox

# Find sandboxes with specific metadata keys
prod_sandboxes = Sandbox.list(
    metadata_exists=["environment", "region"]
)
print(f"With env & region: {len(prod_sandboxes)}")

# Find sandboxes with exact metadata values
prod_us = Sandbox.list(
    metadata_equals={
        "environment": "production",
        "region": "us-east"
    }
)
print(f"Production US-East: {len(prod_us)}")

# Combine metadata filters (AND semantics)
specific = Sandbox.list(
    metadata_exists=["version"],
    metadata_equals={"environment": "staging"}
)
print(f"Staging with version: {len(specific)}")

Filter by Execution Count

from concave import Sandbox

# Get active sandboxes (with executions)
active = Sandbox.list(min_exec_count=1)
print(f"Active: {len(active)} sandboxes")

# Get unused sandboxes
unused = Sandbox.list(max_exec_count=0)
print(f"Unused: {len(unused)} sandboxes")

# Get sandboxes with specific activity range
moderate = Sandbox.list(
    min_exec_count=5,
    max_exec_count=50
)
print(f"5-50 executions: {len(moderate)}")

Combined Filters

from concave import Sandbox
import time

# Get active, internet-enabled sandboxes 
# from the last hour
one_hour_ago = int(time.time()) - 3600
active_recent = Sandbox.list(
    internet_access=True,
    min_exec_count=1,
    since=one_hour_ago
)
print(f"Found: {len(active_recent)} sandboxes")

for sbx in active_recent:
    status = sbx.status()
    print(f"ID: {sbx.id}")
    print(f"  Executions: {status['exec_count']}")
    print(f"  Started: {status['started_at']}")

Clean Up Unused Sandboxes

from concave import Sandbox

# Find and delete sandboxes with no executions
unused = Sandbox.list(max_exec_count=0)
print(f"Found {len(unused)} unused sandboxes")

for sbx in unused:
    sbx.delete()
    print(f"Deleted {sbx.id}")

Exceptions

SandboxAuthenticationErrorException

Raised when API key is invalid or authentication fails.

SandboxTimeoutErrorException

Raised when the list request times out.

ValueErrorException

Raised when API key environment variable is not set.

Error Handling

from concave import (
    Sandbox,
    SandboxAuthenticationError,
    SandboxTimeoutError
)

try:
    sandboxes = Sandbox.list()
    print(f"Found {len(sandboxes)} sandboxes")
except SandboxAuthenticationError as e:
    print(f"Authentication failed: {e}")
except SandboxTimeoutError as e:
    print(f"Request timed out: {e}")
except ValueError as e:
    print(f"Invalid parameters: {e}")