What is a Session?
A session is an isolated browser instance controlled by an AI agent. When you create a session, Enigma provisions a dedicated browser environment and returns connection details.
Think of a session as a private browsing window that persists for the duration of your automation workflow. Each session:
- Has a unique
sessionId for tracking
- Runs in complete isolation from other sessions
- Can execute multiple tasks sequentially
- Persists until terminated or timed out
Session Lifecycle
Sessions progress through several states from creation to completion:
┌─────────┐ ┌──────────┐ ┌─────────────┐
│ Pending │────►│ Active │────►│ Completed │
└─────────┘ └──────────┘ └─────────────┘
│
├───────────► Orphaned ───► Failed
│
├───────────► Terminated
│
└───────────► Failed
Session States
| State | Description | What Happens Next |
|---|
pending | Session initialized, waiting for browser instance assignment | Transitions to active when browser is ready |
active | Task currently running | Can transition to completed, terminated, orphaned, or failed |
orphaned | Instance disconnected unexpectedly | 5-minute grace period for reconnection, then transitions to failed |
completed | Session ended successfully | Final state — session closed |
terminated | Session ended by user request or timeout | Final state — session closed |
failed | Session ended due to error | Final state — session closed |
Orphaned Sessions: If a browser instance loses connection (rare), the session enters a 5-minute grace period. If the instance reconnects within this window, the session resumes. Otherwise, it transitions to failed.
Session Parameters
When creating a session, you can configure these parameters:
| Parameter | Type | Default | Description |
|---|
taskDetails | string | "" | Initial task description (can be empty) |
maxDuration | number | 300000 | Session timeout in ms (max: 300000 = 5 minutes) |
maxInputTokens | number | 100000 | Max input tokens for AI model |
maxOutputTokens | number | 100000 | Max output tokens for AI model |
startingUrl | string | null | Starting URL (e.g., "https://amazon.com") |
avoidDomains | string[] | [] | Domains agent should not visit |
mode | string | "default" | Session mode (currently only “default” supported) |
terminateOnCompletion | boolean | false | Auto-terminate after first task completes |
Example Configuration
{
"taskDetails": "Search for wireless keyboards",
"maxDuration": 180000,
"maxInputTokens": 50000,
"maxOutputTokens": 50000,
"startingUrl": "https://amazon.com",
"avoidDomains": ["facebook.com", "twitter.com"],
"mode": "default",
"terminateOnCompletion": true
}
maxDuration is enforced server-side; sessions cannot exceed 5 minutes (300000ms)taskDetails can be empty if you plan to send tasks laterterminateOnCompletion: true is automatically set for the /start/run-task endpoint
Key Behaviors
One Task at a Time
Each session runs tasks sequentially, not in parallel. If you send a new task while one is running, the new task will queue and start after the current one completes.
Session Timeouts
Sessions have a maximum lifetime of 5 minutes (300000ms). After this duration:
- The session automatically terminates
- Any running task is stopped
- You’re billed only for actual compute time used
Isolation
Sessions are completely isolated from each other:
- No shared cookies or session state
- No shared cache
- Each session starts with a clean browser profile
Auto-Termination
To avoid idle charges, use terminateOnCompletion: true on your final task, or manually terminate the session when done.
Session Types
Persistent Session
Create a session that stays open for multiple tasks:
POST /start/start-session
- You need to execute multiple related tasks
- Tasks depend on previous state (e.g., staying logged in)
- Building complex multi-step workflows
Single-Task Session
Create a session that auto-terminates after one task:
Use when:
- You only need one task executed
- No follow-up actions required
- Simplest integration pattern
