Skip to main content
Sessions allow you to maintain a persistent browser instance and perform multiple actions sequentially. This is useful for complex workflows like logging in, navigating, and extracting data across multiple pages.

How Sessions Work

  1. Create a session by calling POST /task with task=null
  2. Send actions via POST /task/{task_id}/event
  3. Poll for results via GET /task/{task_id}?event_t={timestamp}
  4. Close the session by sending a close event

Step 1: Create a Session

Create a session by submitting a task with task=null. The browser will open and wait for actions.
Response:
Save the id - you’ll use it for all subsequent actions.

Step 2: Send Actions

Use the Event endpoint to send actions to your session. Each action requires:
  • name: The event type (browser_action or session_action)
  • payload: Contains the action name and input parameters
  • id: A unique ID to match the response (use any unique string like UUID)

Run a Task (Agent-powered)

Execute an AI-powered task within the session:

Extract Data

Extract structured data from the current page:

Execute JavaScript

Run custom JavaScript in the browser:

Step 3: Poll for Results

After sending an action, poll the task endpoint to receive the result. Use the event_t parameter to only receive new events.
Response with action result:
Understanding the response:
  • code: 200 - Action succeeded, output contains the result
  • code: 400 - Bad request, output contains error message
  • code: 500 - Internal error, output contains error message
For the next poll, use the last event’s timestamp:

Step 4: Close the Session

When finished, close the session to release resources:

Complete Example: Login and Extract Data

Here’s a complete workflow that logs into a website and extracts user data:

Action Reference

Using the Python SDK

The SDK handles all the polling complexity for you: