Sessions
Create Session
Create a new isolated execution session
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/jsonstring
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
- Active: Session is running and accepting requests
- Idle: No requests for 5 minutes, container sleeps (billed at reduced rate)
- Deep Sleep: No requests for 30 minutes, filesystem saved to storage
- 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
AI Conversations
AI Conversations
Create a session at the start of a conversation. Files and state persist across messages, allowing iterative development.
Code Playgrounds
Code Playgrounds
Give users their own isolated environment to experiment with code.
Agent Workflows
Agent Workflows
Each agent workflow gets its own session with a custom TTL based on expected duration.
Stateful Processing
Stateful Processing
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
Related Endpoints
Get Session Info
Retrieve session details
Delete Session
Delete a session
Execute Code
Run code in the session