Skip to main content
GET
/
browser_sessions
List browser sessions
curl --request GET \
  --url https://api.brightdata.com/browser_sessions \
  --header 'Authorization: Bearer <token>'
{
  "sessions": [
    {
      "session_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "api_name": "scraping_browser1",
      "status": "finished",
      "target_url": "https://www.example.com",
      "end_url": "https://www.example.com/example/sub",
      "navigations": 4,
      "timestamp": "2025-12-16T18:53:41Z",
      "duration": 209.444,
      "captcha": "solved",
      "bandwidth": 123456789,
      "error": null
    },
    {
      "session_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "api_name": "scraping_browser1",
      "status": "failed",
      "target_url": "https://www.another-site.com",
      "end_url": "https://www.another-site.com/examplesubdomain",
      "navigations": 3,
      "timestamp": "2025-12-16T17:20:15Z",
      "duration": 45.2,
      "captcha": "none",
      "bandwidth": 45678901,
      "error": {
        "code": "unknown",
        "message": "Error"
      }
    },
    {
      "session_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "api_name": "scraping_browser1",
      "status": "running",
      "target_url": null,
      "end_url": null,
      "navigations": 0,
      "timestamp": "2025-12-16T19:05:30Z",
      "duration": null,
      "captcha": "none",
      "bandwidth": 0,
      "error": null
    }
  ],
  "count": 3,
  "total": 257,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "has_more": true,
    "next_offset": 50
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt

Use this file to discover all available pages before exploring further.

Default: last 50 sessions sorted by timestamp desc
https://api.brightdata.com/browser_sessions
Get first 25 finished sessions
https://api.brightdata.com/browser_sessions?limit=25&status=finished
Get all running sessions
https://api.brightdata.com/browser_sessions?status=running
Get all failed sessions
https://api.brightdata.com/browser_sessions?status=failed
Get sessions from a specific API zone
https://api.brightdata.com/browser_sessions?api_name=scraping_browser1
Sessions from a specific date range
https://api.brightdata.com/browser_sessions?start_date=2025-12-01T00:00:00Z&end_date=2025-12-16T23:59:59Z
Sessions for a specific target URL sorted by bandwidth
https://api.brightdata.com/browser_sessions?target_url=example.com&sort=bandwidth&order=desc
All sessions for a specific target URL
https://api.brightdata.com/browser_sessions?target_url=amazon.com
Failed sessions for a specific target URL
https://api.brightdata.com/browser_sessions?target_url=linkedin.com&status=failed
Sessions sorted by highest bandwidth
https://api.brightdata.com/browser_sessions?sort=bandwidth&order=desc
Sessions sorted by longest duration
https://api.brightdata.com/browser_sessions?sort=duration&order=desc
First page (100 sessions)
https://api.brightdata.com/browser_sessions?limit=100&offset=0
Second page (next 100 sessions)
https://api.brightdata.com/browser_sessions?limit=100&offset=100

Authorizations

​
Authorization
string
header
required

Use your Bright Data API Key as a Bearer token in the Authorization header.

How to authenticate:

  1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users
  2. Include the API Key in the Authorization header of your requests
  3. Format: Authorization: Bearer YOUR_API_KEY

Example:

Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

Learn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication

Query Parameters

​
api_name
string

Name of the Browser API used

​
limit
integer
default:50

Number of sessions to return

Required range: x <= 100
​
offset
integer
default:0

Pagination offset

​
status
enum<string>
default:all

Filter by session status

Available options:
running,
finished,
failed,
all
​
start_date
string<date-time>

Start date filter

​
end_date
string<date-time>

End date filter

​
target_url
string

Filter by target url (e.g., example.com)

​
end_url
string

Filter by end url (e.g., https://www.example.com/example/sub)

​
sort
enum<string>
default:timestamp

Sort field: timestamp, duration, bandwidth

Available options:
timestamp,
duration,
bandwidth
​
order
enum<string>
default:desc

Sort order: asc or desc

Available options:
asc,
desc

Response

List of sessions

​
sessions
object[]
​
count
integer
​
total
integer
​
pagination
object