feat(api): add sort order to GET /v2/sandboxes

[huv1k]

What

Adds an order=asc|desc query param to GET /v2/sandboxes so clients can request ascending or descending order by sandbox start time. Defaults to desc (the previous hardcoded behavior), so existing callers are unaffected.

Motivated by the dashboard sandbox list, which previously sorted only the pages already loaded client-side. Companion frontend PR: e2b-dev/dashboard#475.

Changes

• No new index/migration. Ascending is implemented as the exact reverse of the existing keyset order (started_at ASC, sandbox_id DESC), which maps onto a backward scan of the existing idx_snapshots_team_time_id (team_id, sandbox_started_at DESC, sandbox_id) index.
• Direction-aware first-page cursor (now for desc, zero-time for asc) via a new Ascending flag on PaginationConfig.
• Ascending variants of the in-memory sort (SortPaginatedSandboxes) and cursor filter (FilterBasedOnCursor), plus a new GetSnapshotsWithCursorAsc sqlc keyset query.
• Threaded the direction through GetV2Sandboxes; the legacy v1 GetSandboxes is untouched.
• Regenerated api.gen.go (oapi-codegen) and the sqlc query.

Scope

Only started_at ordering (asc/desc) — what the dashboard sorts. Sorting by cpu/memory/disk is intentionally out of scope (those live on env_builds and would need new indexes + denormalization).

Test

• go test ./internal/utils/... — ascending default cursor, sort + cursor-filter tie-breaks.
• go test ./pkg/tests/snapshots/... — DB-backed: GetSnapshotsWithCursorAsc returns oldest-first and paginates without gaps/overlaps.
• Manual: GET /v2/sandboxes?order=asc returns oldest-first; EXPLAIN shows a backward index scan (no Sort node) at scale.

[gemini-code-assist]

Code Review

This pull request adds support for sorting sandboxes in ascending order by start time. It updates the pagination configuration, the sandbox list handler, and database queries to support an ascending order parameter, including a new SQL query for ascending keyset pagination. Unit tests and OpenAPI specifications have been updated accordingly. There are no review comments, and we have no additional feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[codecov]

Codecov Report

❌ Patch coverage is 53.22581% with 29 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/api/internal/handlers/sandboxes_list.go	17.14%	29 Missing ⚠️

📢 Thoughts on this report? Let us know!

[mishushakov]

prefer enums to booleans - instead of ascending, it should be direction

type OrderDirection string

const (
    Asc  OrderDirection = "asc"
    Desc OrderDirection = "desc"
)

[huv1k]

prefer enums to booleans - instead of ascending, it should be direction

type OrderDirection string

const (
    Asc  OrderDirection = "asc"
    Desc OrderDirection = "desc"
)

I changed to enum, but we use an int+iota SortDirection instead of a string enum because its zero value is SortDesc — the safe newest-first default — so any PaginationConfig that leaves the field unset (like the templates endpoint) is automatically correct. A string type’s zero value is "", an invalid third state that only behaves like desc by accident and would silently fall through any future exhaustive switch. Keeping it int also makes it a genuinely independent internal type rather than a near-duplicate of the generated api.OrderDirection.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 927fc44b3a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Preserve public startedAt precision

When listing running or pausing sandboxes, this now returns the microsecond-truncated cursor value as the public startedAt, so both /sandboxes and /v2/sandboxes can disagree with the sandbox detail endpoint, which still returns the original sbx.StartTime. The truncation is useful for keyset pagination, but it should be limited to PaginationTimestamp/cursor comparisons so callers do not lose the actual start timestamp in list responses.

Useful? React with 👍 / 👎.