Brightdata SDK JS

Gotchas

• Always await client.close() (or await using). The client holds a keep-alive transport; leaking it hangs the process.
• client.search is SERP-only (google/bing/yandex). To search within a platform, use that platform's discover* / productSearch scraper methods — there is no client.search.amazon.
• chatGPT is camelCase on client.scrape — client.scrape.chatGPT.search(...), not .chatgpt.
• Batch: pass an array, don't loop. scrapeUrl([...urls]) and search.google([...queries]) run in parallel internally. For platform scrapers with many inputs, prefer the orchestrated method with an array, or the *Trigger + job.wait() pattern (see references/advanced.md). Don't wrap blocking calls in Promise.all of single-item calls — you'll fight the rate limiter.
• Orchestrated methods block for minutes. products/profiles/etc. trigger a job and poll until ready (often 2–10 min). Don't set tiny pollTimeouts; tune via { pollInterval, pollTimeout }. Defaults are calibrated.
• Datasets are historical/bulk, not live. Need current data → use platform scrapers or scrapeUrl. query() returns a snapshotId; download() blocks until the snapshot is ready.
• Web unlocker fallback on 403. If a platform scraper is blocked, retry the URL through client.scrapeUrl().
• Don't add your own retry loop. The transport already retries network/timeout errors with backoff; double-retrying wastes credits. Tune timeout / rateLimit on the constructor instead.
• Cost hierarchy (cheapest first): datasets → SERP → platform scrapers → web unlocker → discover → Scraper Studio → Browser API. Prefer the cheapest service that satisfies the request.

Error handling

All errors extend BRDError. Import the specific classes to branch:

import { bdclient, ValidationError, AuthenticationError, BRDError } from '@brightdata/sdk';

try {
  const data = await client.scrape.amazon.products(['https://www.amazon.com/dp/B0D77BX8Y4']);
} catch (err) {
  if (err instanceof AuthenticationError) { /* bad/expired token */ }
  else if (err instanceof ValidationError) { /* bad input */ }
  else if (err instanceof BRDError) { /* any SDK error */ }
  else throw err;
}

Classes: BRDError (base), ValidationError, AuthenticationError, ZoneError, NetworkError, NetworkTimeoutError, TimeoutError, APIError, DataNotReadyError, FSError.

Examples

Scrape a generic page as markdown

const md = await client.scrapeUrl('https://example.com/article', { dataFormat: 'markdown' });

Get an Amazon product (orchestrated — default)

const res = await client.scrape.amazon.products(['https://www.amazon.com/dp/B0D77BX8Y4']);
console.log(res.status, res.rowCount, res.data);

SERP, batched

const results = await client.search.google(['best running shoes', 'best trail shoes'], { country: 'us' });

Find entities (Discover)

const startups = await client.discover('AI startups in Berlin', {
  intent: 'early-stage machine-learning companies',
  numResults: 10,
});

Bulk/historical via datasets

const ds = client.datasets;
const snapshotId = await ds.instagramProfiles.query({ url: 'https://www.instagram.com/natgeo/' }, { records_limit: 50 });
// download() blocks until the snapshot is ready
const rows = await ds.instagramProfiles.download(snapshotId);

Troubleshooting

• AuthenticationError / 401 — token missing or invalid. Check BRIGHTDATA_API_TOKEN or the apiKey option.
• 403 / blocked — site blocked the scraper. Retry the URL via client.scrapeUrl() (web unlocker).
• Timeout — increase timeout (constructor, 1000–300000 ms) or the orchestrated pollTimeout; do not lower it.
• "Dataset not found" — call client.datasets.list(); dataset names are camelCase (amazonProducts, linkedinProfiles).
• Process hangs after work finishes — you forgot await client.close().
• SSL/proxy errors in sandboxes — see references/advanced.md for zone/SSL options.
• Rate-limit errors — set { rateLimit, ratePeriod } on the constructor, or batch via arrays / the trigger pattern instead of Promise.all.

When to load references

• references/scrapers.md — when the user names Amazon, LinkedIn, Facebook, Instagram, YouTube, TikTok, Reddit, Pinterest, ChatGPT, Perplexity, DigiKey — verified per-platform method tables (collect / orchestrated / discover) and the scrapeUrl web-unlocker options.
• references/search.md — SERP engines (search.google/bing/yandex) and the Discover API (discover / discoverTrigger), with all options.
• references/datasets-overview.md — dataset names, the query → getStatus → download lifecycle, and filters.
• references/advanced.md — constructor options & env vars, batch/trigger orchestration, Browser API (Playwright/Puppeteer), Scraper Studio, error classes, and zones/SSL.