Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

feat(sdk,cli): add sandbox list sorting and filters (#1735)

devin-ai-integration[bot]8787dfec9b4c
diff --git a/.changeset/sandbox-list-order-and-filters.md b/.changeset/sandbox-list-order-and-filters.md
new file mode 100644
index 000000000..cdff93531
--- /dev/null
+++ b/.changeset/sandbox-list-order-and-filters.md
@@ -0,0 +1,7 @@
+---
+'e2b': minor
+'@e2b/python-sdk': minor
+'@e2b/cli': minor
+---
+
+Add sorting and new filters to `Sandbox.list`. The `order` option (`'asc'` / `'desc'`, default `'desc'`) sorts sandboxes by start time across the whole paginated dataset, and the query now supports `startedAfter` / `started_after` (inclusive lower bound on start time) and `template` (exact template ID or alias) filters, all applied server-side before pagination. The CLI `e2b sandbox list` command exposes these via `--order`, `--started-after`, and `--template`.
diff --git a/packages/cli/src/commands/sandbox/list.ts b/packages/cli/src/commands/sandbox/list.ts
index a4c716902..310669a63 100644
--- a/packages/cli/src/commands/sandbox/list.ts
+++ b/packages/cli/src/commands/sandbox/list.ts
@@ -1,6 +1,6 @@
import * as tablePrinter from 'console-table-printer'
import * as commander from 'commander'
-import { components, Sandbox, SandboxInfo } from 'e2b'
+import { components, Sandbox, SandboxInfo, SandboxListOrder } from 'e2b'
import { ensureAPIKey } from 'src/api'
import { parseMetadata } from './utils'
@@ -25,6 +25,35 @@ export const listCommand = new commander.Command('list')
(value) => value.split(',')
)
.option('-m, --metadata <metadata>', 'filter by metadata, eg. key1=value1')
+ .option(
+ '-t, --template <template>',
+ 'filter by template ID or alias, eg. base'
+ )
+ .option(
+ '--started-after <date>',
+ 'filter by start time, only sandboxes started at or after this time are returned, eg. 2025-01-01T00:00:00Z',
+ (value) => {
+ const date = new Date(value)
+ if (isNaN(date.getTime())) {
+ throw new commander.InvalidArgumentError(
+ 'Invalid date, expected an ISO 8601 timestamp, eg. 2025-01-01T00:00:00Z'
+ )
+ }
+ return date
+ }
+ )
+ .option(
+ '-o, --order <order>',
+ 'sort order by start time, asc or desc (default: desc)',
+ (value) => {
+ if (value !== 'asc' && value !== 'desc') {
+ throw new commander.InvalidArgumentError(
+ "Invalid order, expected 'asc' or 'desc'"
+ )
+ }
+ return value
+ }
+ )
.option(
'-l, --limit <limit>',
`limit the number of sandboxes returned (default: ${DEFAULT_LIMIT}, 0 for no limit)`,
@@ -41,10 +70,13 @@ export const listCommand = new commander.Command('list')
limit,
state,
metadataRaw: options.metadata,
+ template: options.template,
+ startedAfter: options.startedAfter,
+ order: options.order,
})
if (format === 'pretty') {
- renderTable(sandboxes, state)
+ renderTable(sandboxes, state, options.order)
if (hasMore) {
console.log(
`Showing first ${limit} sandboxes. Use --limit to change.`
@@ -62,12 +94,17 @@ export const listCommand = new commander.Command('list')
}
})
-export function buildTableRows(sandboxes: SandboxInfo[]) {
+export function buildTableRows(
+ sandboxes: SandboxInfo[],
+ order: SandboxListOrder = 'asc'
+) {
+ const sign = order === 'desc' ? -1 : 1
return sandboxes
.slice()
.sort(
(a, b) =>
- new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime() ||
+ sign *
+ (new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime()) ||
a.sandboxId.localeCompare(b.sandboxId)
)
.map((sandbox) => ({
@@ -81,7 +118,8 @@ export function buildTableRows(sandboxes: SandboxInfo[]) {
function renderTable(
sandboxes: SandboxInfo[],
- state: components['schemas']['SandboxState'][]
+ state: components['schemas']['SandboxState'][],
+ order?: SandboxListOrder
) {
if (!sandboxes?.length) {
console.log('No sandboxes found')
@@ -108,7 +146,7 @@ function renderTable(
{ name: 'metadata', alignment: 'left', title: 'Metadata' },
],
disabledColumns: ['clientID'],
- rows: buildTableRows(sandboxes),
+ rows: buildTableRows(sandboxes, order),
style: {
headerTop: {
left: '',
@@ -143,6 +181,9 @@ type ListSandboxesOptions = {
limit?: number
state?: components['schemas']['SandboxState'][]
metadataRaw?: string
+ template?: string
+ startedAfter?: Date
+ order?: SandboxListOrder
}
type ListSandboxesResult = {
@@ -154,6 +195,9 @@ export async function listSandboxes({
limit,
state,
metadataRaw,
+ template,
+ startedAfter,
+ order,
}: ListSandboxesOptions = {}): Promise<ListSandboxesResult> {
const apiKey = ensureAPIKey()
const metadata = parseMetadata(metadataRaw)
@@ -167,7 +211,8 @@ export async function listSandboxes({
const iterator = Sandbox.list({
apiKey: apiKey,
limit: pageLimit,
- query: { state, metadata },
+ query: { state, metadata, template, startedAfter },
+ order,
})
while (iterator.hasNext && (!limit || sandboxes.length < limit)) {
diff --git a/packages/cli/tests/commands/sandbox/list.test.ts b/packages/cli/tests/commands/sandbox/list.test.ts
index 80c613eb2..5beed676a 100644
--- a/packages/cli/tests/commands/sandbox/list.test.ts
+++ b/packages/cli/tests/commands/sandbox/list.test.ts
@@ -39,6 +39,15 @@ describe('sandbox list table rows', () => {
expect(rows.map((r) => r.sandboxId)).toEqual(['sbx-a', 'sbx-b'])
})
+ test('sorts descending when order is desc', () => {
+ const september = sandbox('sbx-sep', new Date('2026-09-01T10:00:00Z'))
+ const october = sandbox('sbx-oct', new Date('2026-10-01T09:00:00Z'))
+
+ const rows = buildTableRows([september, october], 'desc')
+
+ expect(rows.map((r) => r.sandboxId)).toEqual(['sbx-oct', 'sbx-sep'])
+ })
+
test('formats dates and state for display', () => {
const startedAt = new Date('2026-09-01T10:00:00Z')
const [row] = buildTableRows([sandbox('sbx-1', startedAt)])
diff --git a/packages/js-sdk/src/index.ts b/packages/js-sdk/src/index.ts
index b2c321834..a803efcda 100644
--- a/packages/js-sdk/src/index.ts
+++ b/packages/js-sdk/src/index.ts
@@ -65,6 +65,7 @@ export type {
SandboxPauseOpts,
SandboxState,
SandboxListOpts,
+ SandboxListOrder,
SandboxPaginator,
SandboxIamOpts,
SandboxIamToken,
diff --git a/packages/js-sdk/src/sandbox/index.ts b/packages/js-sdk/src/sandbox/index.ts
index 4ae2e8e56..f22de94e0 100644
--- a/packages/js-sdk/src/sandbox/index.ts
+++ b/packages/js-sdk/src/sandbox/index.ts
@@ -236,7 +236,9 @@ export class Sandbox extends SandboxApi {
* `opts.query.state = [...]`.
*
* @param opts connection options, plus optional `query` to filter by
- * metadata / state and `limit` / `nextToken` for pagination.
+ * metadata / state / start time / template, `order` to sort by start
+ * time across the whole result set (not within a page), and `limit` /
+ * `nextToken` for pagination.
*
* @returns a {@link SandboxPaginator} that yields pages of sandboxes
* (running and paused by default). Iterate pages via
diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.ts
index e3dcafce8..3af6b1bac 100644
--- a/packages/js-sdk/src/sandbox/sandboxApi.ts
+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts
@@ -684,6 +684,11 @@ export type SandboxConnectOpts = ConnectionOpts & {
*/
export type SandboxState = 'running' | 'paused'
+/**
+ * Sort order for listing sandboxes by start time.
+ */
+export type SandboxListOrder = 'asc' | 'desc'
+
export interface SandboxListOpts extends Omit<SandboxApiOpts, 'signal'> {
/**
* Filter the list of sandboxes, e.g. by metadata `metadata:{"key": "value"}`, if there are multiple filters they are combined with AND.
@@ -696,8 +701,24 @@ export interface SandboxListOpts extends Omit<SandboxApiOpts, 'signal'> {
* @default ['running', 'paused']
*/
state?: Array<SandboxState>
+ /**
+ * Filter the list of sandboxes to those started at or after this time.
+ */
+ startedAfter?: Date
+ /**
+ * Filter the list of sandboxes by a template ID or name.
+ */
+ template?: string
}
+ /**
+ * Sort order of the list of sandboxes by start time, applied across the
+ * whole result set before pagination (not within a page).
+ *
+ * @default 'desc'
+ */
+ order?: SandboxListOrder
+
/**
* Number of sandboxes to return per page.
*
@@ -1806,11 +1827,13 @@ export class SandboxApi extends ClientFactory {
*/
export class SandboxPaginator extends Paginator<SandboxInfo, SandboxApiOpts> {
private query: SandboxListOpts['query']
+ private order: SandboxListOrder | undefined
constructor(opts?: SandboxListOpts) {
super(opts, opts?.limit, opts?.nextToken)
this.query = opts?.query
+ this.order = opts?.order
}
async nextItems(opts?: SandboxApiOpts): Promise<SandboxInfo[]> {
@@ -1839,6 +1862,9 @@ export class SandboxPaginator extends Paginator<SandboxInfo, SandboxApiOpts> {
query: {
metadata,
state: this.query?.state,
+ startedAfter: this.query?.startedAfter?.toISOString(),
+ template: this.query?.template || undefined,
+ order: this.order,
limit: this.limit,
nextToken: this.nextToken,
},
diff --git a/packages/js-sdk/tests/api/list.test.ts b/packages/js-sdk/tests/api/list.test.ts
index 3960b9fff..52cb8a9f2 100644
--- a/packages/js-sdk/tests/api/list.test.ts
+++ b/packages/js-sdk/tests/api/list.test.ts
@@ -221,6 +221,85 @@ sandboxTest.skipIf(isDebug)(
}
)
+sandboxTest.skipIf(isDebug)(
+ 'list sandboxes with order',
+ async ({ sandbox, sandboxTestId }) => {
+ const extraSbx = await Sandbox.create({ metadata: { sandboxTestId } })
+
+ try {
+ const asc = await Sandbox.list({
+ query: { metadata: { sandboxTestId } },
+ order: 'asc',
+ }).nextItems()
+
+ assert.isAtLeast(asc.length, 2)
+ assert.equal(asc[0].sandboxId, sandbox.sandboxId)
+ assert.equal(asc[asc.length - 1].sandboxId, extraSbx.sandboxId)
+
+ const desc = await Sandbox.list({
+ query: { metadata: { sandboxTestId } },
+ order: 'desc',
+ }).nextItems()
+
+ assert.isAtLeast(desc.length, 2)
+ assert.equal(desc[0].sandboxId, extraSbx.sandboxId)
+ assert.equal(desc[desc.length - 1].sandboxId, sandbox.sandboxId)
+ } finally {
+ await extraSbx.kill()
+ }
+ }
+)
+
+sandboxTest.skipIf(isDebug)(
+ 'list sandboxes started after',
+ async ({ sandbox, sandboxTestId }) => {
+ const info = await sandbox.getInfo()
+
+ const paginator = Sandbox.list({
+ query: {
+ metadata: { sandboxTestId },
+ startedAfter: info.startedAt,
+ },
+ })
+ const sandboxes = await paginator.nextItems()
+
+ assert.isTrue(sandboxes.some((s) => s.sandboxId === sandbox.sandboxId))
+
+ const afterPaginator = Sandbox.list({
+ query: {
+ metadata: { sandboxTestId },
+ startedAfter: new Date(info.startedAt.getTime() + 1000),
+ },
+ })
+ const laterSandboxes = await afterPaginator.nextItems()
+
+ assert.isFalse(
+ laterSandboxes.some((s) => s.sandboxId === sandbox.sandboxId)
+ )
+ }
+)
+
+sandboxTest.skipIf(isDebug)(
+ 'list sandboxes with template filter',
+ async ({ sandbox, sandboxTestId }) => {
+ const info = await sandbox.getInfo()
+
+ const paginator = Sandbox.list({
+ query: { metadata: { sandboxTestId }, template: info.templateId },
+ })
+ const sandboxes = await paginator.nextItems()
+
+ assert.isTrue(sandboxes.some((s) => s.sandboxId === sandbox.sandboxId))
+
+ const unknownPaginator = Sandbox.list({
+ query: { metadata: { sandboxTestId }, template: 'unknown-template' },
+ })
+ const unknownSandboxes = await unknownPaginator.nextItems()
+
+ assert.equal(unknownSandboxes.length, 0)
+ }
+)
+
sandboxTest.skipIf(isDebug)(
'list sandboxes',
async ({ sandbox, sandboxTestId }) => {
diff --git a/packages/python-sdk/e2b/__init__.py b/packages/python-sdk/e2b/__init__.py
index 3b13505d1..1d3cac9f4 100644
--- a/packages/python-sdk/e2b/__init__.py
+++ b/packages/python-sdk/e2b/__init__.py
@@ -100,6 +100,7 @@ from .sandbox.sandbox_api import (
SandboxNetworkTransformContext,
SandboxNetworkTransformResolver,
SandboxNetworkUpdate,
+ SandboxListOrder,
SandboxQuery,
SandboxState,
SnapshotInfo,
@@ -195,6 +196,7 @@ __all__ = [
"SandboxInfoLifecycle",
"SandboxMetrics",
"ProcessInfo",
+ "SandboxListOrder",
"SandboxQuery",
"SandboxState",
"SandboxMetrics",
diff --git a/packages/python-sdk/e2b/sandbox/sandbox_api.py b/packages/python-sdk/e2b/sandbox/sandbox_api.py
index c13d0d28b..d53c84915 100644
--- a/packages/python-sdk/e2b/sandbox/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox/sandbox_api.py
@@ -1045,6 +1045,10 @@ class SandboxInfo:
)
+SandboxListOrder = Literal["asc", "desc"]
+"""Sort order for listing sandboxes by start time."""
+
+
@dataclass
class SandboxQuery:
"""Query parameters for listing sandboxes."""
@@ -1055,6 +1059,12 @@ class SandboxQuery:
state: Optional[list[SandboxState]] = None
"""Filter sandboxes by state."""
+ started_after: Optional[datetime] = None
+ """Filter sandboxes to those started at or after this time. Naive datetimes are interpreted as local time."""
+
+ template: Optional[str] = None
+ """Filter sandboxes by a template ID or name."""
+
@dataclass
class SandboxMetrics:
@@ -1108,7 +1118,9 @@ class SandboxPaginatorBase(PaginatorBase[SandboxInfo, ApiParams]):
query: Optional[SandboxQuery] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ order: Optional[SandboxListOrder] = None,
**opts: Unpack[ApiParams],
):
super().__init__(limit=limit, next_token=next_token, **opts)
self.query = query
+ self.order = order
diff --git a/packages/python-sdk/e2b/sandbox_async/paginator.py b/packages/python-sdk/e2b/sandbox_async/paginator.py
index 9d19d09b4..ee5af6960 100644
--- a/packages/python-sdk/e2b/sandbox_async/paginator.py
+++ b/packages/python-sdk/e2b/sandbox_async/paginator.py
@@ -7,7 +7,7 @@ from e2b.api.client.api.sandboxes import get_v2_sandboxes
from e2b.api.client.api.snapshots import get_snapshots
from e2b.api.client.types import UNSET
from e2b.connection_config import ApiParams, ConnectionConfig, merge_api_params
-from e2b.exceptions import SandboxException
+from e2b.exceptions import InvalidArgumentException, SandboxException
from e2b.sandbox.sandbox_api import (
SandboxPaginatorBase,
SandboxInfo,
@@ -16,6 +16,7 @@ from e2b.sandbox.sandbox_api import (
)
from e2b.api import handle_api_exception
from e2b.api.client.models.error import Error
+from e2b.api.client.models.order_direction import OrderDirection
from e2b.api.client_async import get_api_client
@@ -57,12 +58,31 @@ class AsyncSandboxPaginator(SandboxPaginatorBase):
}
metadata = urllib.parse.urlencode(quoted_metadata)
+ if self.order is None:
+ order = UNSET
+ else:
+ try:
+ order = OrderDirection(self.order)
+ except ValueError:
+ raise InvalidArgumentException(
+ f"Invalid order {self.order!r}, expected 'asc' or 'desc'"
+ )
+
config = ConnectionConfig(**merge_api_params(self._opts, opts))
api_client = get_api_client(config)
res = await get_v2_sandboxes.asyncio_detailed(
client=api_client,
metadata=metadata if metadata else UNSET,
state=self.query.state if self.query and self.query.state else UNSET,
+ started_after=(
+ self.query.started_after.astimezone()
+ if self.query and self.query.started_after
+ else UNSET
+ ),
+ template=(
+ self.query.template if self.query and self.query.template else UNSET
+ ),
+ order=order,
limit=self.limit if self.limit else UNSET,
next_token=self._next_token if self._next_token else UNSET,
)
diff --git a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
index ced697c14..b6a208d6a 100644
--- a/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_async/sandbox_api.py
@@ -52,6 +52,7 @@ from e2b.sandbox.sandbox_api import (
SandboxIamOpts,
SandboxInfo,
SandboxLifecycle,
+ SandboxListOrder,
SandboxMetrics,
SandboxNetworkOpts,
SandboxNetworkUpdate,
@@ -71,6 +72,7 @@ class SandboxApi(SandboxBase):
query: Optional[SandboxQuery] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ order: Optional[SandboxListOrder] = None,
**opts: Unpack[ApiParams],
) -> AsyncSandboxPaginator:
"""
@@ -79,9 +81,10 @@ class SandboxApi(SandboxBase):
By default (no `query.state` set), returns sandboxes in both `running`
and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`.
- :param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])`
+ :param query: Filter the list of sandboxes by metadata, state, start time, or template, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])`
:param limit: Maximum number of sandboxes to return per page
:param next_token: Token for pagination
+ :param order: Sort order of the list of sandboxes by start time, applied across the whole result set before pagination (not within a page), defaults to `"desc"` (newest first)
:return: An `AsyncSandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `await paginator.next_items()` while `paginator.has_next` is True.
"""
@@ -89,6 +92,7 @@ class SandboxApi(SandboxBase):
query=query,
limit=limit,
next_token=next_token,
+ order=order,
**cls._resolve_api_params(**opts),
)
diff --git a/packages/python-sdk/e2b/sandbox_sync/paginator.py b/packages/python-sdk/e2b/sandbox_sync/paginator.py
index a88ad5d27..6538dd6f2 100644
--- a/packages/python-sdk/e2b/sandbox_sync/paginator.py
+++ b/packages/python-sdk/e2b/sandbox_sync/paginator.py
@@ -7,9 +7,10 @@ from e2b.api import handle_api_exception
from e2b.api.client.api.sandboxes import get_v2_sandboxes
from e2b.api.client.api.snapshots import get_snapshots
from e2b.api.client.models.error import Error
+from e2b.api.client.models.order_direction import OrderDirection
from e2b.api.client.types import UNSET
from e2b.connection_config import ApiParams, ConnectionConfig, merge_api_params
-from e2b.exceptions import SandboxException
+from e2b.exceptions import InvalidArgumentException, SandboxException
from e2b.sandbox.sandbox_api import (
SandboxPaginatorBase,
SandboxInfo,
@@ -57,12 +58,31 @@ class SandboxPaginator(SandboxPaginatorBase):
}
metadata = urllib.parse.urlencode(quoted_metadata)
+ if self.order is None:
+ order = UNSET
+ else:
+ try:
+ order = OrderDirection(self.order)
+ except ValueError:
+ raise InvalidArgumentException(
+ f"Invalid order {self.order!r}, expected 'asc' or 'desc'"
+ )
+
config = ConnectionConfig(**merge_api_params(self._opts, opts))
api_client = get_api_client(config)
res = get_v2_sandboxes.sync_detailed(
client=api_client,
metadata=metadata if metadata else UNSET,
state=self.query.state if self.query and self.query.state else UNSET,
+ started_after=(
+ self.query.started_after.astimezone()
+ if self.query and self.query.started_after
+ else UNSET
+ ),
+ template=(
+ self.query.template if self.query and self.query.template else UNSET
+ ),
+ order=order,
limit=self.limit if self.limit else UNSET,
next_token=self._next_token if self._next_token else UNSET,
)
diff --git a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
index 0fc615e21..ff8dc4a3e 100644
--- a/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
+++ b/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py
@@ -51,6 +51,7 @@ from e2b.sandbox.sandbox_api import (
SandboxIamOpts,
SandboxInfo,
SandboxLifecycle,
+ SandboxListOrder,
SandboxMetrics,
SandboxNetworkOpts,
SandboxNetworkUpdate,
@@ -70,6 +71,7 @@ class SandboxApi(SandboxBase):
query: Optional[SandboxQuery] = None,
limit: Optional[int] = None,
next_token: Optional[str] = None,
+ order: Optional[SandboxListOrder] = None,
**opts: Unpack[ApiParams],
) -> SandboxPaginator:
"""
@@ -78,9 +80,10 @@ class SandboxApi(SandboxBase):
By default (no `query.state` set), returns sandboxes in both `running`
and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`.
- :param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])`
+ :param query: Filter the list of sandboxes by metadata, state, start time, or template, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])`
:param limit: Maximum number of sandboxes to return per page
:param next_token: Token for pagination
+ :param order: Sort order of the list of sandboxes by start time, applied across the whole result set before pagination (not within a page), defaults to `"desc"` (newest first)
:return: A `SandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `paginator.next_items()` while `paginator.has_next` is True.
"""
@@ -88,6 +91,7 @@ class SandboxApi(SandboxBase):
query=query,
limit=limit,
next_token=next_token,
+ order=order,
**cls._resolve_api_params(**opts),
)
diff --git a/packages/python-sdk/tests/async/api_async/test_sbx_list.py b/packages/python-sdk/tests/async/api_async/test_sbx_list.py
index e902fd9a0..a78d42ec8 100644
--- a/packages/python-sdk/tests/async/api_async/test_sbx_list.py
+++ b/packages/python-sdk/tests/async/api_async/test_sbx_list.py
@@ -1,4 +1,5 @@
import uuid
+from datetime import timedelta
import pytest
@@ -175,6 +176,83 @@ async def test_paginate_running_and_paused_sandboxes(
assert sandboxes2[0].sandbox_id == async_sandbox.sandbox_id
+async def test_list_sandboxes_with_order(
+ async_sandbox: AsyncSandbox, async_sandbox_factory, sandbox_test_id: str
+):
+ extra_sbx = await async_sandbox_factory(
+ metadata={"sandbox_test_id": sandbox_test_id}
+ )
+
+ paginator = AsyncSandbox.list(
+ query=SandboxQuery(metadata={"sandbox_test_id": sandbox_test_id}),
+ order="asc",
+ )
+ asc = await paginator.next_items()
+ assert len(asc) >= 2
+ assert asc[0].sandbox_id == async_sandbox.sandbox_id
+ assert asc[-1].sandbox_id == extra_sbx.sandbox_id
+
+ paginator = AsyncSandbox.list(
+ query=SandboxQuery(metadata={"sandbox_test_id": sandbox_test_id}),
+ order="desc",
+ )
+ desc = await paginator.next_items()
+ assert len(desc) >= 2
+ assert desc[0].sandbox_id == extra_sbx.sandbox_id
+ assert desc[-1].sandbox_id == async_sandbox.sandbox_id
+
+
+async def test_list_sandboxes_started_after(
+ async_sandbox: AsyncSandbox, sandbox_test_id: str
+):
+ info = await async_sandbox.get_info()
+
+ paginator = AsyncSandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ started_after=info.started_at,
+ )
+ )
+ sandboxes = await paginator.next_items()
+ assert async_sandbox.sandbox_id in [sbx.sandbox_id for sbx in sandboxes]
+
+ paginator = AsyncSandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ started_after=info.started_at + timedelta(seconds=1),
+ )
+ )
+ later_sandboxes = await paginator.next_items()
+ assert async_sandbox.sandbox_id not in [sbx.sandbox_id for sbx in later_sandboxes]
+
+
+async def test_list_sandboxes_with_template_filter(
+ async_sandbox: AsyncSandbox, sandbox_test_id: str
+):
+ info = await async_sandbox.get_info()
+
+ paginator = AsyncSandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ template=info.template_id,
+ )
+ )
+ sandboxes = await paginator.next_items()
+ assert async_sandbox.sandbox_id in [sbx.sandbox_id for sbx in sandboxes]
+
+ paginator = AsyncSandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ template="unknown-template",
+ )
+ )
+ unknown_sandboxes = await paginator.next_items()
+ assert len(unknown_sandboxes) == 0
+
+
@pytest.mark.skip_debug()
async def test_paginate_iterator(async_sandbox: AsyncSandbox, sandbox_test_id: str):
paginator = AsyncSandbox.list(
diff --git a/packages/python-sdk/tests/sync/api_sync/test_sbx_list.py b/packages/python-sdk/tests/sync/api_sync/test_sbx_list.py
index c139ccbd8..a7de9b024 100644
--- a/packages/python-sdk/tests/sync/api_sync/test_sbx_list.py
+++ b/packages/python-sdk/tests/sync/api_sync/test_sbx_list.py
@@ -1,4 +1,5 @@
import uuid
+from datetime import timedelta
import pytest
@@ -174,6 +175,77 @@ def test_paginate_running_and_paused_sandboxes(
assert sandboxes[0].sandbox_id == sandbox.sandbox_id
+def test_list_sandboxes_with_order(
+ sandbox: Sandbox, sandbox_factory, sandbox_test_id: str
+):
+ extra_sbx = sandbox_factory(metadata={"sandbox_test_id": sandbox_test_id})
+
+ paginator = Sandbox.list(
+ query=SandboxQuery(metadata={"sandbox_test_id": sandbox_test_id}),
+ order="asc",
+ )
+ asc = paginator.next_items()
+ assert len(asc) >= 2
+ assert asc[0].sandbox_id == sandbox.sandbox_id
+ assert asc[-1].sandbox_id == extra_sbx.sandbox_id
+
+ paginator = Sandbox.list(
+ query=SandboxQuery(metadata={"sandbox_test_id": sandbox_test_id}),
+ order="desc",
+ )
+ desc = paginator.next_items()
+ assert len(desc) >= 2
+ assert desc[0].sandbox_id == extra_sbx.sandbox_id
+ assert desc[-1].sandbox_id == sandbox.sandbox_id
+
+
+def test_list_sandboxes_started_after(sandbox: Sandbox, sandbox_test_id: str):
+ info = sandbox.get_info()
+
+ paginator = Sandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ started_after=info.started_at,
+ )
+ )
+ sandboxes = paginator.next_items()
+ assert sandbox.sandbox_id in [sbx.sandbox_id for sbx in sandboxes]
+
+ paginator = Sandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ started_after=info.started_at + timedelta(seconds=1),
+ )
+ )
+ later_sandboxes = paginator.next_items()
+ assert sandbox.sandbox_id not in [sbx.sandbox_id for sbx in later_sandboxes]
+
+
+def test_list_sandboxes_with_template_filter(sandbox: Sandbox, sandbox_test_id: str):
+ info = sandbox.get_info()
+
+ paginator = Sandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ template=info.template_id,
+ )
+ )
+ sandboxes = paginator.next_items()
+ assert sandbox.sandbox_id in [sbx.sandbox_id for sbx in sandboxes]
+
+ paginator = Sandbox.list(
+ query=SandboxQuery(
+ metadata={"sandbox_test_id": sandbox_test_id},
+ template="unknown-template",
+ )
+ )
+ unknown_sandboxes = paginator.next_items()
+ assert len(unknown_sandboxes) == 0
+
+
@pytest.mark.skip_debug()
def test_paginate_iterator(sandbox: Sandbox, sandbox_test_id: str):
paginator = Sandbox.list(