Skip to main content
POST

Overview

Creates a new session that provides an isolated Bun runtime environment. Sessions persist files, processes, and state across multiple API calls during a conversation or workflow.

Request

string
required
Bearer token with your API key
string
required
Must be application/json
string
Unique key to safely retry requests

Request Body

integer
Time-to-live in seconds. Default: 86400 (24 hours). Max: 604800 (7 days)
object
Custom metadata to attach to the session (max 16KB)
object
Override default resource limits (paid plans only)

Response

string
required
Unique identifier for the session (format: ses_ + alphanumeric)
string
required
ISO 8601 timestamp when the session will be deleted
string
required
URL for accessing web apps running in this session
string
required
ISO 8601 timestamp when the session was created
object
required
Applied resource limits

Example

Session Lifecycle

  1. Active: Session is running and accepting requests
  2. Idle: No requests for 5 minutes, container sleeps (billed at reduced rate)
  3. Deep Sleep: No requests for 30 minutes, filesystem saved to storage
  4. Expired: TTL reached, session and all data deleted
Sessions automatically wake from sleep when you make a request. Wake time is typically under 3 seconds.

Use Cases

Create a session at the start of a conversation. Files and state persist across messages, allowing iterative development.
Give users their own isolated environment to experiment with code.
Each agent workflow gets its own session with a custom TTL based on expected duration.
Run databases or other stateful services that need to persist between API calls.

Best Practices

Set appropriate TTL

Use shorter TTLs (1 hour) for ephemeral tasks, longer (24 hours) for conversations

Use metadata

Track sessions with metadata for easier debugging and analytics

Idempotency keys

Use idempotency keys when retrying failed requests to avoid duplicate sessions

Clean up

Delete sessions when done to free resources and reduce costs

Limits

Get Session Info

Retrieve session details

Delete Session

Delete a session

Execute Code

Run code in the session