Sessions let you lease a worker for stateful, multi-call interactions.
What's a Session?
Normally, each task runs on whatever worker is available. The worker might change between calls, and state doesn't persist.
A session locks a specific worker to you:
code
1Regular calls: Sessions:23Task 1 → Worker A Task 1 ┐4Task 2 → Worker B ↓ │5Task 3 → Worker A Task 2 ├→ Worker A (leased)6 ↓ │7 Task 3 ┘With sessions:
- Same worker handles all your calls
- State persists in memory between calls
- Faster responses — no cold starts after the first call
Session Lifecycle
code
1┌─────────┐ ┌─────────┐ ┌─────────┐2│ Create │ ──▶ │ Active │ ──▶ │ Ended │3└─────────┘ └─────────┘ └─────────┘4 │5 ▼6 ┌─────────┐7 │ Expired │8 └─────────┘- Create — Request
session: "new"to start a session - Active — Worker is leased to you; make calls with the session ID
- Ended — You explicitly end the session, or...
- Expired — Session times out after idle period (default: 60 seconds, customizable 1s-1h)
When to Use Sessions
Use Sessions When
| Scenario | Example |
|---|---|
| Stateful interactions | Browser automation, code interpreters |
| Multi-step operations | Load data → Process → Export |
| Interactive workflows | User provides input between steps |
| Accumulated state | Conversation history, running calculations |
Use Regular Calls When
| Scenario | Example |
|---|---|
| Stateless operations | Image generation, text completion |
| Single requests | One-off API calls |
| Maximum throughput | High-volume batch processing |
How It Works
Starting a Session
Pass session: "new" to create a session:
python
1result = client.run({2 "app": "my-app",3 "input": {...},4 "session": "new" # Start new session5})67session_id = result["session_id"] # e.g., "sess_abc123"Custom Session Timeout
By default, sessions expire after 60 seconds of inactivity. Customize this with session_timeout (1-3600 seconds):
python
1# Create a session with 5-minute idle timeout2result = client.run({3 "app": "my-app",4 "input": {...},5 "session": "new",6 "session_timeout": 300 # 5 minutes7})Each successful call resets the idle timer. See Sessions Developer Guide for full details.
Continuing a Session
Use the session ID for subsequent calls:
python
1result = client.run({2 "app": "my-app",3 "input": {...},4 "session": session_id # Use existing session5})Ending a Session
Explicitly end when done (releases the worker):
python
1client.sessions.end(session_id)Or let it expire automatically after the idle timeout.
Multi-Function Apps
Sessions work with any app, including multi-function apps. Call different functions within the same session:
python
1# Start session2result = client.run({3 "app": "browser-app",4 "function": "navigate",5 "input": {"url": "https://example.com"},6 "session": "new"7})8session_id = result["session_id"]910# Continue with different function11result = client.run({12 "app": "browser-app",13 "function": "click",14 "input": {"selector": "#login"},15 "session": session_id16})1718# Another function19result = client.run({20 "app": "browser-app",21 "function": "screenshot",22 "input": {},23 "session": session_id24})Next
- Sessions Developer Guide — Full API reference
- Stateful Sessions Examples — Practical patterns