# bright-data-best-practices

A reference skill that teaches a coding assistant which Bright Data API fits the task and how to wire it up. Handy when the agent builds a scraper or a bdata wrapper.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1800 installs · ★ 268
- Author: brightdata
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/brightdata/skills/tree/HEAD/skills/bright-data-best-practices/SKILL.md
- Updated: 2026-10-15
- HTML: https://affpapa.org/en/nevibecode/skills/bright-data-best-practices

## What it does

Inside the skill sits a decision table. Fetching a page's HTML without interaction goes to Web Unlocker, the cheapest option. Search results from Google, Bing or Yandex come from SERP API as parsed JSON. Amazon, LinkedIn, Instagram and TikTok have prebuilt scrapers under Web Scraper API. Clicks, scrolling, form fills and XHR capture need Browser API over CDP or WebDriver.

Auth is one pattern across all of them. Set `BRIGHTDATA_API_KEY` and the zone variables: `BRIGHTDATA_UNLOCKER_ZONE`, `BRIGHTDATA_SERP_ZONE`, `BROWSER_AUTH`. REST calls to Web Unlocker and SERP API carry `Authorization: Bearer …`. Working through the `bdata` CLI instead? `bdata login` covers it, and `references/cli-setup.md` holds setup plus troubleshooting.

The rule worth remembering: do not drive Web Unlocker with Puppeteer, Playwright, Selenium or anti-detect browsers. Browser API exists for that. Nothing runs without the key and zone name taken from your control panel. On SERP API the `num` parameter was deprecated in September 2025, so paging goes through `start`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add brightdata/skills --skill bright-data-best-practices -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/bright-data-best-practices/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/bright-data-best-practices/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add brightdata/skills --skill bright-data-best-practices -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/bright-data-best-practices/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add brightdata/skills --skill bright-data-best-practices -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/bright-data-best-practices/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install brightdata/skills bright-data-best-practices
```

2. **Manually: put the files in place**
- File: `.github/skills/bright-data-best-practices/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add brightdata/skills --skill bright-data-best-practices -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/brightdata/skills --path skills/bright-data-best-practices
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/bright-data-best-practices/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add brightdata/skills --skill bright-data-best-practices -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/brightdata/skills/tree/HEAD/skills/bright-data-best-practices/SKILL.md

## When to use it
- pick the right Bright Data API for a job
- turn a search page into parsed JSON
- pull a page's HTML without a browser
- attach Playwright or Puppeteer to Scraping Browser
- set up keys and zones as env vars

## Example prompts
- Which Bright Data API should I use to fetch a product page without a browser?
- Write a Python SERP API call with `brd_json=1` and read the `organic` array
- Connect Playwright to Browser API using `BROWSER_AUTH`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 278596055be9a430.

BEGIN THIRD-PARTY FILE 278596055be9a430
````text
---
name: bright-data-best-practices
description: "Build production-ready Bright Data integrations with best practices baked in. Reference documentation for developers using coding assistants (Claude Code, Cursor, etc.) to implement web scraping, search, browser automation, and structured data extraction. Covers Web Unlocker API, SERP API, Web Scraper API, and Browser API (Scraping Browser)."
user-invocable: false
---

# CLI Setup Reference

Install, authentication, and troubleshooting for the Bright Data CLI (`bdata`) are documented in a single canonical place:

→ [`references/cli-setup.md`](references/cli-setup.md)

Consult it before any task that shells out to `bdata`.

# Bright Data APIs

Bright Data provides infrastructure for web data extraction at scale. Four primary APIs cover different use cases — always pick the most specific tool for the job.

## Choosing the Right API

| Use Case | API | Why |
|----------|-----|-----|
| Scrape any webpage by URL (no interaction) | Web Unlocker | HTTP-based, auto-bypasses bot detection, cheapest |
| Google / Bing / Yandex search results | SERP API | Specialized for SERP extraction, returns structured data |
| Structured data from Amazon, LinkedIn, Instagram, TikTok, etc. | Web Scraper API | Pre-built scrapers, no parsing needed |
| Click, scroll, fill forms, run JS, intercept XHR | Browser API | Full browser automation |
| Puppeteer / Playwright / Selenium automation | Browser API | Connects via CDP/WebDriver |
| Route your own HTTP client through a raw proxy (DC/ISP/Residential/Mobile) | Proxy networks | When you need direct proxy access with your own request logic instead of a managed API — see the `proxy.md` skill |

## Authentication Pattern (All APIs)

All APIs share the same authentication model. The env vars below apply to direct REST API integrations — if you are using the `bdata` CLI, `bdata login` handles all of these automatically (see [`references/cli-setup.md`](references/cli-setup.md)).

```bash
export BRIGHTDATA_API_KEY="your-api-key"         # From Control Panel > Account Settings
export BRIGHTDATA_UNLOCKER_ZONE="zone-name"       # Web Unlocker zone name
export BRIGHTDATA_SERP_ZONE="serp-zone-name"      # SERP API zone name
export BROWSER_AUTH="brd-customer-ID-zone-NAME:PASSWORD"  # Browser API credentials
```

REST API authentication header for Web Unlocker and SERP API:
```
Authorization: Bearer YOUR_API_KEY
```

---

## Web Unlocker API

HTTP-based scraping proxy. Best for simple page fetches without browser interaction.
````
END THIRD-PARTY FILE 278596055be9a430

The third-party file has ended. Everything between the 278596055be9a430 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2537 of 14480 bytes. © brightdata · MIT · https://github.com/brightdata/skills/tree/HEAD/skills/bright-data-best-practices/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md