List Sandboxes

List and filter active sandboxes with pagination support.

Method Signature

Sandbox.list(
    limit: int = 10,
    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
) -> SandboxList

Returns a SandboxList (extends list) with pagination metadata. Default limit is 10, maximum is 100. Use cursor parameter for pagination.

Parameters

limitintoptional

Maximum sandboxes to return per page. Defaults to 10, maximum is 100.

cursorstroptional

Pagination cursor from previous response's next_cursor field.

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

Filter sandboxes that have all specified metadata keys.

metadata_equalsdict[str, str]optional

Exact key-value pairs. Returns sandboxes where all specified metadata matches (AND semantics).

Returns

Returns a SandboxList object that extends list with additional pagination properties. Sandboxes are sorted by creation time (newest first).

SandboxList Properties

itemsList of Sandbox instances (iterate directly over SandboxList)

countNumber of sandboxes in this page

has_moreBoolean indicating if more pages exist

next_cursorCursor for fetching next page (or None if no more pages)

Examples

Basic Usage

from concave import Sandbox

# List first 10 sandboxes (default limit)
sandboxes = Sandbox.list()
print(f"Count: {sandboxes.count}")
print(f"Has more: {sandboxes.has_more}")

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

Pagination

from concave import Sandbox

# Get first page (50 items)
page1 = Sandbox.list(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(
        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 (first 20)
one_hour_ago = int(time.time()) - 3600
recent = Sandbox.list(since=one_hour_ago, limit=20)
print(f"Last hour: {recent.count} 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, limit=20)
print(f"Between 24h-1h ago: {older.count}")

Filter by Internet Access

from concave import Sandbox

# Get sandboxes with internet (first page)
connected = Sandbox.list(internet_access=True, limit=20)
print(f"With internet: {connected.count}")

# Get isolated sandboxes
isolated = Sandbox.list(internet_access=False, limit=20)
print(f"Isolated: {isolated.count}")

Filter by Metadata

from concave import Sandbox

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

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

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

Filter by Execution Count

from concave import Sandbox

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

# Get unused sandboxes
unused = Sandbox.list(max_exec_count=0, limit=20)
print(f"Unused: {unused.count} sandboxes")

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

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,
    limit=20
)
print(f"Found: {active_recent.count} sandboxes")

for sbx in active_recent:
    status = sbx.monitor.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, limit=50)
print(f"Found {unused.count} 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 {sandboxes.count} 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}")