creating, running, paused, destroying, and
destroyed. Pausing preserves filesystem and memory state so that resuming is
fast and cheap. The start endpoint is a convenience that handles every
transition (creating → running, paused → running, dev server boot) in a
single atomic call.
Required scope for all four endpoints:
sessions:write.You usually don’t need to resume explicitly. Sessions auto-pause after
roughly 20 minutes idle, and the endpoints you’d reach for next resume in
place rather than rejecting:
- the file endpoints (read, write, list, search, upload, download, mkdir, rename, delete) and
run-server - the terminal WebSocket, which backs
runtm-api session execandsession connect - the prompt WebSocket
POST /api/v2/sessions/{id}/start
400 with the reason rather than a bare
“not running”. Call resume explicitly when you want to warm a sandbox ahead
of time, or pause when you deliberately want to stop the clock.Pause Session
POST /api/sessions/{session_id}/pause
Pauses a running session. The sandbox is snapshotted (filesystem and
memory) and held for the duration of your plan’s paused-session retention.
While paused, sessions accrue no compute cost but are not interactive.
Calling pause on an already-paused session is a no-op and returns 200.
Calling pause while a prompt is actively running returns 409.
Path Parameters
Query Parameters
Why the session was paused. Reasonable values:
manual, inactivity,
e2b_auto, ttl_expired. Surfaces in activity logs only.Response
Resume Session
POST /api/sessions/{session_id}/resume
Resumes a paused session, restoring the exact state captured at pause time.
Custom instructions, environment variables, and template secrets are
re-injected. Calling resume on an already-running session is a no-op.
Path Parameters
Response
Start Session
POST /api/sessions/{session_id}/start
Convenience endpoint that always returns a running sandbox with the dev
server up (or an explicit error). It handles every transition transparently:
creating→ polls the sandbox until provisioning completes, then starts the dev server.paused→ resumes and starts the dev server.running→ idempotent: starts/checks the dev server, no-op if already up.destroyed/error/destroying→ returns410.
Path Parameters
Response
Cleanup Old Paused Sessions
POST /api/sessions/cleanup
Triggers an idempotent maintenance pass that:
- Sends warning notifications for sessions approaching their paused-retention limit.
- Destroys sessions that have exceeded their plan’s paused retention period.
90 days on the
free plan, indefinite on paid plans (configured per session at pause time).
This is a maintenance trigger and is not required for normal operation -
the platform runs the same pass on a schedule. Calling it more often does
not extend or shorten any individual session’s retention; sessions are
only acted on once their retention has elapsed.