curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

With timeout and keepAlive:

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "timeout": 300,
  "keepAlive": true
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

With proxy enabled (requires paid plan):

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "proxies": true
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Note: Proxies are not available on the free plan. You'll receive a 402 error if you try to use this feature without upgrading.

With specific region (us-west-2, us-east-1, eu-central-1, ap-southeast-1):

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "region": "us-west-2"
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Response includes:

id - Session ID to use for connections
connectUrl - WebSocket URL for Playwright/Puppeteer
seleniumRemoteUrl - URL for Selenium connections
signingKey - Key for HTTP connections

2. List Sessions

List all sessions with optional filters:

curl -s -X GET "https://api.browserbase.com/v1/sessions" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Filter by status (RUNNING, ERROR, TIMED_OUT, COMPLETED):

curl -s -X GET "https://api.browserbase.com/v1/sessions?status=RUNNING" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Query by user metadata:

Note: The query syntax for user metadata filtering uses single quotes: user_metadata['key']:'value'. To avoid complex shell escaping, write the query to a file and use --data-urlencode "q@filename".

Write /tmp/query.txt with content:

user_metadata['test']:'true'

Then query sessions:

curl -s -X GET -G "https://api.browserbase.com/v1/sessions" --data-urlencode "q@/tmp/query.txt" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

More examples:

Query by stagehand metadata - write /tmp/query.txt:

user_metadata['stagehand']:'true'

Query by environment - write /tmp/query.txt:

user_metadata['env']:'production'

Then run:

curl -s -X GET -G "https://api.browserbase.com/v1/sessions" --data-urlencode "q@/tmp/query.txt" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

3. Get Session Details

Get details of a specific session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

4. Update Session (Release)

Request to release a session before its timeout to avoid additional charges. Replace <your-session-id> with the actual session ID:

Write /tmp/request.json:

{
  "status": "REQUEST_RELEASE"
}

curl -s -X POST "https://api.browserbase.com/v1/sessions/<your-session-id>" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

The session status will change to COMPLETED and endedAt timestamp will be set.

5. Get Debug/Live URLs

Get live debugging URLs for a running session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/debug" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Note: Debug URLs may only be available after a browser client has connected to the session via WebSocket.

Response includes:

debuggerUrl - Chrome DevTools debugger URL
debuggerFullscreenUrl - Fullscreen debugger view
wsUrl - WebSocket URL
pages - Array of open pages with their debugger URLs

6. Get Session Logs

Retrieve logs from a session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/logs" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

7. Get Session Recording

Get the rrweb recording of a session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/recording" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

8. Get Session Downloads

Retrieve files downloaded during a session (returns ZIP file). Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/downloads" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" --output downloads.zip

9. Upload Files to Session

Upload files to use in a browser session. Replace <your-session-id> with the actual session ID:

curl -s -X POST "https://api.browserbase.com/v1/sessions/<your-session-id>/uploads" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -F "file=@/path/to/file.pdf"

Contexts API

Contexts allow you to persist cookies, cache, and session storage across multiple browser sessions.

Create a Context

Write /tmp/request.json:

{
  "projectId": "<your-project-id>"
}

curl -s -X POST "https://api.browserbase.com/v1/contexts" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Save the returned id to use in sessions.

Get Context Details

Retrieve details of a specific context. Replace <your-context-id> with the actual context ID:

curl -s -X GET "https://api.browserbase.com/v1/contexts/<your-context-id>" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Response includes:

id - Context identifier
createdAt - Creation timestamp
updatedAt - Last update timestamp
projectId - The Project ID linked to the context

Create Session with Context

Use an existing context to restore cookies and login state. Replace <your-context-id> with the actual context ID:

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "browserSettings": {
    "context": {
      "id": "<your-context-id>",
      "persist": true
    }
  }
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Set persist: true to save updates back to the context after the session ends.

Delete Context

Delete a context when it's no longer needed. Replace <your-context-id> with the actual context ID:

curl -s -X DELETE "https://api.browserbase.com/v1/contexts/<your-context-id>" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -w "\nHTTP Status: %{http_code}"

Successful deletion returns HTTP 204 (No Content).

Projects API

Get Project Usage

Retrieve project-wide usage statistics (browser minutes and proxy bytes). Replace <your-project-id> with your actual project ID:

curl -s -X GET "https://api.browserbase.com/v1/projects/<your-project-id>/usage" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

API Endpoints Reference

Endpoint	Method	Description
`/v1/sessions`	POST	Create a new browser session
`/v1/sessions`	GET	List all sessions
`/v1/sessions/{id}`	GET	Get session details (returns array)
`/v1/sessions/{id}`	POST	Update session (release)
`/v1/sessions/{id}/debug`	GET	Get live debug URLs
`/v1/sessions/{id}/logs`	GET	Get session logs
`/v1/sessions/{id}/recording`	GET	Get session recording (rrweb)
`/v1/sessions/{id}/downloads`	GET	Get downloaded files (ZIP)
`/v1/sessions/{id}/uploads`	POST	Upload files to session
`/v1/contexts`	POST	Create a new context
`/v1/contexts/{id}`	GET	Get context details
`/v1/contexts/{id}`	DELETE	Delete a context
`/v1/projects/{id}/usage`	GET	Get project usage stats

Session Status Values

Status	Description
`RUNNING`	Session is currently active
`COMPLETED`	Session ended successfully
`ERROR`	Session ended with an error
`TIMED_OUT`	Session exceeded timeout
`REQUEST_RELEASE`	Request to end session

Guidelines

Session Lifecycle: Sessions auto-terminate after timeout (default 5 minutes). Use keepAlive: true for longer sessions.
Contexts: Use contexts to persist login state and avoid repeated authentication.
Proxies: Enable proxies for geo-restricted content or to avoid rate limiting.
Regions: Choose a region close to your target websites for better performance.
Debug URLs: Use debug URLs for real-time human-in-the-loop debugging.
Recordings: Session replays use rrweb DOM reconstruction, not video files.
Rate Limits: Check your plan limits in the Browserbase dashboard.

browserbase

Troubleshooting

How to Use

1. Create a Session