Bright Data — Agent Onboarding

Install

# macOS / Linux — fastest install
curl -fsSL https://cli.brightdata.com/install.sh | bash

# Cross-platform (or if you don't want the install script)
npm install -g @brightdata/cli

# One-off, no install
npx --yes --package @brightdata/cli brightdata <command>

bdata login

1. Opens the browser for OAuth (or use bdata login --device on headless / SSH machines)
2. Saves the API key locally — you never need to paste a token again
3. Auto-creates the required proxy zones (cli_unlocker, cli_browser)
4. Sets sensible default configuration

bdata login --api-key <key>
# or
export BRIGHTDATA_API_KEY=<key>

bdata version
bdata config            # confirms auth + zones
bdata zones             # should list cli_unlocker, cli_browser
bdata budget            # confirms account + balance

• If bdata config or bdata budget exits non-zero, route to Path C (auth) before continuing.
• If either exits zero but its output contains an auth or zone error string (e.g. unauthorized, invalid api key, not logged in, no such zone, zone not found), treat it as a failure and route to Path C.
• Only proceed to a path below when both commands exit zero and show an authenticated account with the cli_unlocker / cli_browser zones.

Install agent skills (optional, recommended)

# Interactive picker — choose skills + target agent
bdata skill add

# Install a specific skill
bdata skill add scrape
bdata skill add data-feeds
bdata skill add competitive-intel

# See everything available
bdata skill list

Choose your path

Path A — Live web tools (CLI)

• brightdata-cli — overall command surface (scrape, search, pipelines, status, zones, budget, config)
• search — discovery via bdata search (Google / Bing / Yandex SERP, structured JSON)
• scrape — clean content from a known URL via bdata scrape (markdown / HTML / JSON / screenshot)
• data-feeds — structured records from 40+ supported platforms via bdata pipelines <type> (Amazon, LinkedIn, Instagram, TikTok, YouTube, Reddit, Crunchbase, Google Maps, …)
• discover-api — intent-ranked semantic web search via bdata discover (relevance-scored results + optional page content)
• scraper-studio — generate and run an AI-built scraper from a plain-English description via bdata scraper create / bdata scraper run
• competitive-intel — packaged competitor / pricing / review / hiring / SEO analyses on top of the CLI
• price-comparison — "where is this cheapest, in stock?" across Amazon, Walmart, eBay, Best Buy, Google Shopping, into one ranked table
• brand-listening — social-listening / sentiment digest of what people are saying about a brand across Reddit, X, TikTok, news, reviews
• live-research — multi-query Discover → dedup → a cited research brief
• seo-audit — sitemap-stratified live SEO audits

1. Search first when you need discovery bdata search "query" --json
2. Pipelines next if the target is a supported platform — you get structured JSON with no parsing bdata pipelines amazon_product "https://amazon.com/dp/..."
3. Scrape when you have a URL and no platform pipeline applies bdata scrape "https://example.com" -f markdown
4. Browser API only when the page truly needs clicks, forms, or login (see the brightdata-cli skill for bdata browser and the bright-data-best-practices browser-api reference)

Path B — Integrate Bright Data into an app

What should Bright Data do in the product?

Pick a stack

• Python → use the official SDK
  bashCopy

  pip install brightdata-sdk

  Hand off to python-sdk-best-practices for client setup (async/sync), platform scrapers, SERP, datasets, Browser API, and error handling.
• Node / TypeScript → use the official JS/TS SDK
  bashCopy

  npm install @brightdata/sdk

  Hand off to js-sdk-best-practices for client setup (bdclient), platform scrapers, SERP, Discover, datasets, Browser API, Scraper Studio, and error handling.
• Shell / other languages → call the REST API directly (Path D below has the endpoints), or use the CLI as a library via npx @brightdata/cli.
• Raw proxy access (route HTTP through Bright Data IPs) → hand off to proxy for network/pool choice, the brd-customer- username format, SSL CA setup, and framework integrations.
• Web-grounded retrieval / RAG for an LLM → hand off to rag-pipeline (Discover as the retrieval / ingestion layer).
• LLM tool layer (Claude, ChatGPT, etc.) → use the MCP server (Path M).

Set credentials

BRIGHTDATA_API_KEY=...
BRIGHTDATA_UNLOCKER_ZONE=cli_unlocker   # created automatically by `bdata login`
BRIGHTDATA_SERP_ZONE=cli_unlocker       # or a dedicated SERP zone

Smoke test before writing real code

# Web Unlocker via REST
curl -sS https://api.brightdata.com/request \
  -H "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "zone": "'"$BRIGHTDATA_UNLOCKER_ZONE"'",
    "format": "raw",
    "data_format": "markdown"
  }' | head -40

Path M — MCP server (LLM tool layer)

Path C — Get an API key (auth only)

Free tier — no card needed to start. Every new account gets 5,000 free credits / month (~$7.50) from one shared pool, so you can build and test before depositing anything. The docs are the source of truth for these numbers: https://docs.brightdata.com/general/account/billing-and-pricing/free-tier

• Shared pool across Unlocker API, SERP API, Web Scraper API, and Scraper Studio — 1 credit per request/record (Scraper Studio: 1 credit per page load).
• Bright Data MCP server requests draw from the same pool — MCP runs on the Unlocker API.
• Hard stop when credits run out if no funds are deposited — never a surprise bill.
• Credits reset on the 1st of each month and do not roll over.
• Not covered by monthly credits: Proxy products and the Browser API. Those use a separate one-time $2 trial (7 days) plus a $5 bonus (30 days) after adding a payment method.
• Not eligible: custom-PAYG and pre-commit plans.

Easiest: use the CLI's OAuth flow

bdata login            # browser-based OAuth
bdata login --device   # headless / SSH (device-code flow)

Manual: dashboard

1. Go to https://brightdata.com/cp (sign up if needed)
2. Create a Web Unlocker zone ("Add" → "Unlocker zone")
3. Copy the API key from the dashboard
4. Save it where the rest of the app reads secrets:

echo "BRIGHTDATA_API_KEY=..." >> .env
echo "BRIGHTDATA_UNLOCKER_ZONE=<zone-name>" >> .env

Verify

bdata budget    # any successful response means the key works

Path D — Use Bright Data without installing anything

• Human pastes it in — if a key already exists, set BRIGHTDATA_API_KEY=... and BRIGHTDATA_UNLOCKER_ZONE=... in the environment
• Browser flow — do Path C; the dashboard issues both

Core endpoints

# Web Unlocker — clean content from any URL
POST /request
{
  "url": "https://target.com",
  "zone": "<unlocker-zone>",
  "format": "raw",
  "data_format": "markdown"   // or "html", "screenshot", "parsed_light"
}

# SERP API — structured search results
# Use the same /request endpoint with a SERP zone and a search URL,
# adding `brd_json=1` to receive parsed JSON instead of raw HTML.
POST /request
{
  "url": "https://www.google.com/search?q=web+scraping&brd_json=1",
  "zone": "<serp-zone>",
  "format": "raw"
}

# Web Scraper API — structured data for 40+ platforms (async)
POST /datasets/v3/trigger?dataset_id=<id>
[ { "url": "https://amazon.com/dp/B09V3KXJPB" } ]

# then poll
GET  /datasets/v3/snapshot/<snapshot_id>?format=json

Documentation

• Product docs: https://docs.brightdata.com
• LLM-friendly docs index: https://docs.brightdata.com/llms.txt
• Dashboard (zones, keys, billing): https://brightdata.com/cp

After onboarding — where to go next

• scraper-builder vs scraper-studio — scraper-builder writes a scraper you own and run yourself (real code + selectors + pagination). scraper-studio turns a URL + plain-English description into an AI-generated Bright Data collector you run via bdata scraper create / bdata scraper run — no code to maintain.
• competitive-intel vs price-comparison — competitive-intel is business analysis of a competitor's pricing strategy and positioning; price-comparison is consumer purchase research ("where is this product cheapest and in stock").