ScrapeBadger CLI

Google Light Search uses the dedicated /v1/google/light/search endpoint:

scrapebadger google light-search "vinted api" --gl us --hl en

Light returns organic results and related searches for 10 credits per successful uncached request. Regular scrapebadger google search costs 20 credits and returns the full SERP. Cache hits and failed requests are free.

Command-line access to ScrapeBadger APIs, including Etsy, AliExpress, Target, ASOS, Best Buy, search engines, social media and general web scraping.

Install

pip install scrapebadger-cli
# or: uv tool install scrapebadger-cli

The installed command is scrapebadger. To run without installing:

uvx --from scrapebadger-cli scrapebadger --help

Quick Start

scrapebadger login                 # approve in the browser; or: scrapebadger login --api-key sb_live_...
scrapebadger twitter user elonmusk
scrapebadger twitter search "AI agents" --output table
scrapebadger vinted search "nike shoes" --market de
scrapebadger web scrape https://example.com --js

Getting a key and setting up agents (0.24.0+)

scrapebadger init                  # detect Claude Code / Codex / Cursor; install skill + MCP
scrapebadger init --yes --all      # same, without prompts
scrapebadger login                 # device flow: open the link, approve, key is saved
scrapebadger trial                 # 50 free credits without an account (one per network, 7 days)
scrapebadger connect               # print the link that attaches a trial key to an account

init installs the ScrapeBadger skill (SKILL.md and references/endpoints.md) into ~/.claude/skills/scrapebadger and ~/.codex/skills/scrapebadger, registers the hosted MCP server (claude mcp add --scope user ..., codex mcp add ..., or a merge into ~/.cursor/mcp.json that keeps your other servers), and offers login or trial when no key is configured. Cursor has no on-disk global rules location, so it gets the MCP server only.

trial solves a short proof of work, saves the key and prints a notice to pass on to your human. A trial key works only from the IP that created it, on read APIs, at 10 requests/min, and not through the hosted MCP server. It refuses to replace an account key unless you pass --force.

Saved results and free re-reads

Every API command also writes its full JSON response to ~/.cache/scrapebadger/results/<api>-<command>-<UTC timestamp>.json (honours XDG_CACHE_HOME; the newest 200 are kept) and prints one line to stderr:

saved: ~/.cache/scrapebadger/results/google-search-20261023T101500123456Z.json · credits: 20 · result_id: 6f1c...

stdout is unchanged. Disable with scrapebadger --no-save ... or SCRAPEBADGER_SAVE=0.

Re-slice a saved result locally, for free:

scrapebadger view --summary                       # newest result: types, list lengths, byte sizes
scrapebadger view --last google --max-items 5 --fields title,link
scrapebadger view path/to/result.json --jq '.organic_results[].link'   # needs jq on PATH

--fields (dotted paths) and --max-items apply to the main item list (the top-level array, else the largest top-level list); truncation adds "_truncated": {"path", "kept", "total"}.

Re-read a result from the server within ~15 minutes, free, sliced server-side:

scrapebadger results get <result_id> --max-items 3 --fields id,text

Quotes, bug reports and feedback (all free)

scrapebadger quote /v1/google/search -p q="coffee" -p gl=us     # cost, validation, latency
scrapebadger quote /v1/web/scrape --method POST --body '{"url": "https://example.com"}'
scrapebadger report-bug "Empty results for a public profile" --request-id <X-Request-ID> --endpoint /v1/instagram/users/x
scrapebadger feedback "Please add Pinterest" --details "..."

Error messages include the request_id to quote in a bug report, and the upgrade or claim link when you are out of credits.

Environment

Vinted mobile data (0.14.0+)

scrapebadger vinted mobile-operations
scrapebadger vinted mobile sold-comparables --market fr --params '{"catalog_id":"1242","brand_id":"53","status_id":"2"}'
scrapebadger vinted search "nike" --sizes 206 --materials 43

The catalog lists 76 public read operations with parameter types and examples. Each mobile read costs 1 credit; discovery is free. Sold comparables are a Vinted-selected sample, not a complete sales history or guaranteed final sale prices.

Vinted image search

scrapebadger vinted search-by-image --image photo.jpg --market nl --price-to 50
scrapebadger vinted search-by-image --image-url https://example.com/photo.webp --brand-ids 53

Provide exactly one of --image, --image-url or --image-base64. JPEG, PNG and WebP up to 5 MiB are supported. Returns active listings in visual ranking order; 10 credits per successful request. Filter with --catalog-ids, --brand-ids, --status-ids, --color-ids, --size-ids, --material-ids and price bounds. Resend the same image and --time from pagination when requesting --page 2.

Dedicated ecommerce APIs

scrapebadger etsy search "ceramic mug" --currency USD --country US
scrapebadger aliexpress search "keyboard"
scrapebadger target search "laptop" --zip-code 55403 --store-id 1375
scrapebadger asos search "shoes" --market uk
scrapebadger bestbuy search "laptop"

Run scrapebadger <api> --help to list product, review, store, availability and reference commands for that API. Each command supports --help for its exact parameters. Requests use your API key's existing permissions and credit balance.