brd-browser-debug

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

1. Present a health summary: total from the response, counts of finished / failed / running.
2. Most recent session — always highlight it regardless of status (same detail level as single-session mode).
3. 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.
4. 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."

5. 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.
6. Captcha activity — report how many sessions hit captchas and whether they were solved.
7. 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}

1. 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.

2. 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

3. 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.