Skip to main content
A session is an isolated compute environment where Deck executes tasks. Sessions are created automatically when you run a task, or you can reuse an existing session to run multiple tasks in the same environment.

​
How sessions fit in

When you run a task, Deck creates a session (or reuses one you specify) and executes the work. The session manages the compute lifecycle so your application doesn’t have to.

​
Session lifecycle

Sessions are created implicitly when a task runs. You don’t need to create them ahead of time. The response includes a session_id you can reuse.

​
Reusing a session

To run additional tasks in the same session, pass the session_id from a previous task run: POST /v2/tasks/{task_id}/run 
{
  "session_id": "sess_x9y8z7...",
  "input": {
    "check_in_date": "2026-05-01"
  }
}
Reusing a session runs the task in an already-open environment. This is faster and preserves any state from previous tasks.

​
Session statuses

StatusMeaning
queuedWaiting to be provisioned
runningActive and executing work
completingWork is done, session is shutting down
completedAll work finished and the session was closed
failedThe session encountered an error

​
Ending a session

POST /v2/sessions/{session_id}/end
This closes the browser and transitions the session to completed. Any running task runs in the session will be canceled. Sessions are also cleaned up automatically after the last task run completes or after a period of inactivity, so ending a session explicitly is optional.

​
When to reuse sessions

Reuse a session when you need to run multiple tasks for the same user in quick succession. A common pattern is to run a task and then immediately follow up with related tasks in the same session.