Bright Data — Browser Session Debugger
Diagnose Bright Data Scraping Browser sessions using the Browser Sessions API. Fetches live session data and performs smart triage: error diagnosis, bandwidth analysis, captcha reporting, and pattern detection across recent sessions.
Setup
Set your API key:
export BRIGHTDATA_API_KEY="your-api-key"
Get a key from Bright Data Dashboard → API Tokens.
No zone configuration needed — zone is returned as a field in session data.
Usage
List & triage recent sessions
Invoked as /brd-browser-debug with no arguments.
API reference: GET /browser_sessions
Fetching sessions
Start with a single call using limit=100 (the maximum) sorted by most recent:
GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
Authorization: Bearer $BRIGHTDATA_API_KEY
Pagination: The response includes total, has_more, and next_offset. If has_more is true and the analysis requires more data (e.g. bandwidth outlier detection needs a larger sample), fetch the next page using offset=<next_offset>. Continue until you have enough data or has_more is false.
Available filters — apply when the user specifies a scope:
status=failed|finished|running — narrow to a specific session state
api_name=<zone> — filter to a specific Bright Data zone
target_url=<domain> — filter by target domain (e.g. ksp.co.il)
start_date / end_date — ISO 8601 datetime range
sort=timestamp|duration|bandwidth with order=asc|desc
If the user asks about a specific zone, date range, or domain — apply the relevant filter rather than fetching all sessions and filtering client-side.
Triage steps
- Present a health summary:
total from the response, counts of finished / failed / running.
- Most recent session — always highlight it regardless of status (same detail level as single-session mode).
- Failed sessions — for each failure: session ID, timestamp, duration, bandwidth, then reason about the cause using the signals in the Diagnosing Failed Sessions section below.
- Pattern detection — if 3+ sessions share the same
error.code, call it a systemic issue:
"3 sessions failed with custom_headers — you are overriding a header Bright Data forbids. Remove page.setExtraHTTPHeaders() from your code."
- Bandwidth outliers — group sessions by
target_url domain. For each domain with 3+ sessions, calculate the median bandwidth. Flag any session whose bandwidth exceeds 2× the median for that domain as an outlier, and note if it was a failed session that burned unusually high bandwidth before dying.
- Captcha activity — report how many sessions hit captchas and whether they were solved.
- Close with a one-line verdict: the most important finding and the most impactful fix.
Inspect a single session
Invoked as /brd-browser-debug <session_id>.
API reference: GET /browser_sessions/{session_id}
Call:
GET https://api.brightdata.com/browser_sessions/<session_id>
Authorization: Bearer $BRIGHTDATA_API_KEY
Returns 404 if the session ID is not found — tell the user and stop.
Present a deep-dive using the response fields:
- Status (
status): running / finished / failed
- Zone (
api_name): the Bright Data zone that handled the session
- Timestamp (
timestamp): ISO 8601 — show in local-friendly format
- Duration (
duration): seconds (nullable) — flag if < 2 s on failure (session barely started)
- Bandwidth (
bandwidth): convert bytes → MB
- Navigations (
navigations): flag if 0 (nothing was loaded)
- Captcha (
captcha): one of solved / none / detected / failed — detected means a challenge appeared but was not solved; failed means solving was attempted but unsuccessful
- Route:
target_url → end_url — note significant drift (different domain, login wall, error page)
- Error (
error.code + error.message): reason about the cause using the signals in Diagnosing Failed Sessions below
Close with a one-line verdict.
Auto-detect from conversation context
When a Bright Data browser issue appears in the conversation — including puppeteer stack traces, error codes, mention of brd.superproxy.io, the user describing a session failure, OR a scraper producing empty/unexpected results (e.g. "Found 0 categories", "Got 0 products", fewer items than expected):
- If a session ID is visible in the output → run single-session deep-dive on it.
- If no session ID is visible → run list & triage, filtering by the relevant target domain. Highlight the most recent session as the likely culprit.
- Cross-reference the error or unexpected behavior seen in the conversation with what the API returns. A session that finished successfully with normal bandwidth but the scraper got 0 results points to a client-side selector/extraction bug, not a proxy issue.
Features
- Smart triage: automatically groups sessions by failure pattern, not just lists them
- Dynamic bandwidth outliers: compares sessions per domain using median, flags sessions exceeding 2× the median
- Captcha reporting: shows captcha hit rate and solve rate
- Error reasoning: reads session signals holistically to infer what went wrong
- Zero config: reads API key from env var, no zone setup needed
Diagnosing Failed Sessions
Do not rely on the error code alone. Cross-reference all available session signals to reason about what went wrong:
- Duration + navigations: a session that failed in < 2 s with 0 navigations never got past the connection phase — likely a configuration or auth issue. A session that ran for minutes before failing points to a runtime problem (blocked mid-scrape, idle timeout, network drop).
- Bandwidth relative to other sessions: a failed session that consumed bandwidth similar to successful ones likely reached the target but failed during extraction. A failed session with near-zero bandwidth never loaded anything.
- Captcha field: if
captcha is detected but not solved, the session was stopped by an unsolved challenge — suggest enabling captcha solving on the zone.
- target_url vs end_url: significant drift (different domain, login page, error page) means the session was redirected away from the intended target.
- error.message: use the raw message text as-is to describe what happened — do not guess or invent meaning beyond what the message says. If the cause is unclear, direct the user to Bright Data support.
1---
2name: brd-browser-debug
3description: "Debug Bright Data Scraping Browser sessions using the Browser Sessions API. Use this skill when the user encounters a Bright Data browser session error, puppeteer stack trace, failed scraper run, or asks about session bandwidth, duration, captchas, or connection issues. Also use when a Bright Data scraper produces unexpected results such as empty data, 0 items found, missing products, or fewer results than expected — session data can reveal whether the issue is network/proxy-side (blocks, captchas, redirects, timeouts) or client-side (selectors, extraction logic). Triggers on phrases like 'why did my session fail', 'debug my bright data session', 'check my scraping browser sessions', 'how much bandwidth did my scraper use', 'got 0 results', 'found 0', 'scraper returned empty', 'scraper not working', 'script didn't work', or when a Bright Data error code or brd.superproxy.io stack trace appears in the conversation. Requires BRIGHTDATA_API_KEY environment variable."
4user-invocable: true
5metadata:
6 source: https://skillmd.com/skills/brightdata/brd-browser-debug
7---
8
9# Bright Data — Browser Session Debugger
10
11Diagnose Bright Data Scraping Browser sessions using the Browser Sessions API. Fetches live session data and performs smart triage: error diagnosis, bandwidth analysis, captcha reporting, and pattern detection across recent sessions.
12
13## Setup
14
15**Set your API key:**
16```bash
17export BRIGHTDATA_API_KEY="your-api-key"
18```
19
20Get a key from [Bright Data Dashboard → API Tokens](https://brightdata.com/cp/setting/users).
21
22No zone configuration needed — zone is returned as a field in session data.
23
24## Usage
25
26### List & triage recent sessions
27
28Invoked as `/brd-browser-debug` with no arguments.
29
30**API reference:** [GET /browser_sessions](https://docs.brightdata.com/api-reference/browser-api/get-sessions)
31
32#### Fetching sessions
33
34Start with a single call using `limit=100` (the maximum) sorted by most recent:
35```
36GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
37Authorization: Bearer $BRIGHTDATA_API_KEY
38```
39
40**Pagination:** The response includes `total`, `has_more`, and `next_offset`. If `has_more` is true and the analysis requires more data (e.g. bandwidth outlier detection needs a larger sample), fetch the next page using `offset=<next_offset>`. Continue until you have enough data or `has_more` is false.
41
42**Available filters** — apply when the user specifies a scope:
43- `status=failed|finished|running` — narrow to a specific session state
44- `api_name=<zone>` — filter to a specific Bright Data zone
45- `target_url=<domain>` — filter by target domain (e.g. `ksp.co.il`)
46- `start_date` / `end_date` — ISO 8601 datetime range
47- `sort=timestamp|duration|bandwidth` with `order=asc|desc`
48
49If the user asks about a specific zone, date range, or domain — apply the relevant filter rather than fetching all sessions and filtering client-side.
50
51#### Triage steps
52
531. Present a **health summary**: `total` from the response, counts of finished / failed / running.
542. **Most recent session** — always highlight it regardless of status (same detail level as single-session mode).
553. **Failed sessions** — for each failure: session ID, timestamp, duration, bandwidth, then reason about the cause using the signals in the Diagnosing Failed Sessions section below.
564. **Pattern detection** — if 3+ sessions share the same `error.code`, call it a systemic issue:
57 > "3 sessions failed with `custom_headers` — you are overriding a header Bright Data forbids. Remove `page.setExtraHTTPHeaders()` from your code."
585. **Bandwidth outliers** — group sessions by `target_url` domain. For each domain with 3+ sessions, calculate the median bandwidth. Flag any session whose bandwidth exceeds 2× the median for that domain as an outlier, and note if it was a failed session that burned unusually high bandwidth before dying.
596. **Captcha activity** — report how many sessions hit captchas and whether they were solved.
607. Close with a **one-line verdict**: the most important finding and the most impactful fix.
61
62### Inspect a single session
63
64Invoked as `/brd-browser-debug <session_id>`.
65
66**API reference:** [GET /browser_sessions/{session_id}](https://docs.brightdata.com/api-reference/browser-api/get-session)
67
681. Call:
69 ```
70 GET https://api.brightdata.com/browser_sessions/<session_id>
71 Authorization: Bearer $BRIGHTDATA_API_KEY
72 ```
73 Returns 404 if the session ID is not found — tell the user and stop.
74
752. Present a **deep-dive** using the response fields:
76 - **Status** (`status`): `running` / `finished` / `failed`
77 - **Zone** (`api_name`): the Bright Data zone that handled the session
78 - **Timestamp** (`timestamp`): ISO 8601 — show in local-friendly format
79 - **Duration** (`duration`): seconds (nullable) — flag if < 2 s on failure (session barely started)
80 - **Bandwidth** (`bandwidth`): convert bytes → MB
81 - **Navigations** (`navigations`): flag if 0 (nothing was loaded)
82 - **Captcha** (`captcha`): one of `solved` / `none` / `detected` / `failed` — `detected` means a challenge appeared but was not solved; `failed` means solving was attempted but unsuccessful
83 - **Route**: `target_url` → `end_url` — note significant drift (different domain, login wall, error page)
84 - **Error** (`error.code` + `error.message`): reason about the cause using the signals in Diagnosing Failed Sessions below
853. Close with a **one-line verdict**.
86
87### Auto-detect from conversation context
88
89When a Bright Data browser issue appears in the conversation — including puppeteer stack traces, error codes, mention of `brd.superproxy.io`, the user describing a session failure, OR a scraper producing empty/unexpected results (e.g. "Found 0 categories", "Got 0 products", fewer items than expected):
90
91- If a session ID is visible in the output → run **single-session** deep-dive on it.
92- If no session ID is visible → run **list & triage**, filtering by the relevant target domain. Highlight the most recent session as the likely culprit.
93- Cross-reference the error or unexpected behavior seen in the conversation with what the API returns. A session that finished successfully with normal bandwidth but the scraper got 0 results points to a client-side selector/extraction bug, not a proxy issue.
94
95## Features
96
97- **Smart triage**: automatically groups sessions by failure pattern, not just lists them
98- **Dynamic bandwidth outliers**: compares sessions per domain using median, flags sessions exceeding 2× the median
99- **Captcha reporting**: shows captcha hit rate and solve rate
100- **Error reasoning**: reads session signals holistically to infer what went wrong
101- **Zero config**: reads API key from env var, no zone setup needed
102
103## Diagnosing Failed Sessions
104
105Do not rely on the error code alone. Cross-reference all available session signals to reason about what went wrong:
106
107- **Duration + navigations**: a session that failed in < 2 s with 0 navigations never got past the connection phase — likely a configuration or auth issue. A session that ran for minutes before failing points to a runtime problem (blocked mid-scrape, idle timeout, network drop).
108- **Bandwidth relative to other sessions**: a failed session that consumed bandwidth similar to successful ones likely reached the target but failed during extraction. A failed session with near-zero bandwidth never loaded anything.
109- **Captcha field**: if `captcha` is `detected` but not `solved`, the session was stopped by an unsolved challenge — suggest enabling captcha solving on the zone.
110- **target_url vs end_url**: significant drift (different domain, login page, error page) means the session was redirected away from the intended target.
111- **error.message**: use the raw message text as-is to describe what happened — do not guess or invent meaning beyond what the message says. If the cause is unclear, direct the user to [Bright Data support](https://help.brightdata.com).