List Browser Sessions
Get paginated list of browser sessions with optional status filtering.
List responses intentionally omit per-session presigned recording URLs
(recording_url is always null here). Each recording URL requires a
synchronous boto3 SigV4 signing call (plus an S3 HEAD) that holds the GIL
and blocks the event loop. With page_size up to the max this CPU-pegs the
worker and starves the DB pool, cascading into pool exhaustion across the
fleet. Clients should fetch the recording URL on demand via
GET /api/v2/browsers/{id}, which signs exactly one URL for a single
session. Mirrors the v3 sessions list fix (ENG-4904, PR #4621).
const options = {method: 'GET', headers: {'X-Browser-Use-API-Key': '<api-key>'}};
fetch('https://api.browser-use.com/api/v2/browsers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request GET \
--url https://api.browser-use.com/api/v2/browsers \
--header 'X-Browser-Use-API-Key: <api-key>'import requests
url = "https://api.browser-use.com/api/v2/browsers"
headers = {"X-Browser-Use-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "active",
"timeoutAt": "2023-11-07T05:31:56Z",
"startedAt": "2023-11-07T05:31:56Z",
"liveUrl": "<string>",
"cdpUrl": "<string>",
"finishedAt": "2023-11-07T05:31:56Z",
"proxyUsedMb": "0",
"proxyCost": "0",
"browserCost": "0",
"agentSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"recordingUrl": "<string>",
"metadata": {},
"extensions": []
}
],
"totalItems": 123,
"pageNumber": 123,
"pageSize": 123
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Query Parameters
Only browsers tagged with every one of these terms. key matches any value; key=value matches exactly. Repeat the param to require more than one (AND).
1 <= x <= 100x >= 1Enumeration of possible browser session states
Attributes: ACTIVE: Session is currently active and running (browser is running) STOPPED: Session has been stopped and is no longer active (browser is stopped)
active, stopped Response
Successful Response
Response model for paginated browser session list requests.
Was this page helpful?
const options = {method: 'GET', headers: {'X-Browser-Use-API-Key': '<api-key>'}};
fetch('https://api.browser-use.com/api/v2/browsers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request GET \
--url https://api.browser-use.com/api/v2/browsers \
--header 'X-Browser-Use-API-Key: <api-key>'import requests
url = "https://api.browser-use.com/api/v2/browsers"
headers = {"X-Browser-Use-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "active",
"timeoutAt": "2023-11-07T05:31:56Z",
"startedAt": "2023-11-07T05:31:56Z",
"liveUrl": "<string>",
"cdpUrl": "<string>",
"finishedAt": "2023-11-07T05:31:56Z",
"proxyUsedMb": "0",
"proxyCost": "0",
"browserCost": "0",
"agentSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"recordingUrl": "<string>",
"metadata": {},
"extensions": []
}
],
"totalItems": 123,
"pageNumber": 123,
"pageSize": 123
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}