# ScrapeBadger — Full API Reference for LLMs

> This file provides complete API endpoint documentation for AI agents and LLMs.

## Authentication

All API requests require an API key passed as `X-API-Key` header.
Base URL: https://scrapebadger.com

## MCP Server

Endpoint: https://mcp.scrapebadger.com/mcp
Auth: Authorization: Bearer <api_key> header or ?api_key=<key> query param
Tools: 63 total (Twitter, Vinted, Web Scraping)

---

## Twitter/X API (35 endpoints)

### Users
- GET /v1/twitter/users/{username}/by_username — Get profile by username
- GET /v1/twitter/users/{user_id}/by_id — Get profile by numeric ID
- GET /v1/twitter/users/batch_by_ids?user_ids=id1,id2 — Batch get by IDs
- GET /v1/twitter/users/batch_by_usernames?usernames=a,b — Batch get by usernames
- GET /v1/twitter/users/search_users?query=... — Search users
- GET /v1/twitter/users/{username}/followers — Get followers
- GET /v1/twitter/users/{username}/followings — Get following
- GET /v1/twitter/users/{username}/mentions — Get mentions
- GET /v1/twitter/users/{user_id}/subscriptions — Get subscriptions
- GET /v1/twitter/users/{user_id}/articles — Get long-form articles

### Tweets
- GET /v1/twitter/tweets/tweet/{tweet_id} — Get tweet details
- GET /v1/twitter/tweets/?tweets=id1,id2 — Get multiple tweets
- GET /v1/twitter/tweets/advanced_search?query=...&query_type=Latest&count=20 — Advanced search
- GET /v1/twitter/tweets/tweet/{tweet_id}/replies — Get replies
- GET /v1/twitter/tweets/tweet/{tweet_id}/quotes — Get quote tweets
- GET /v1/twitter/tweets/tweet/{tweet_id}/retweeters — Get retweeters
- GET /v1/twitter/tweets/tweet/{tweet_id}/favoriters — Get likes
- GET /v1/twitter/tweets/tweet/{tweet_id}/similar — Get similar tweets
- GET /v1/twitter/tweets/tweet/{tweet_id}/edit_history — Get edit history
- GET /v1/twitter/tweets/tweet/{tweet_id}/community_notes — Get community notes
- GET /v1/twitter/tweets/article/{article_id} — Get article

### Communities
- GET /v1/twitter/communities/{community_id} — Get community
- GET /v1/twitter/communities/{community_id}/tweets — Get community tweets
- GET /v1/twitter/communities/search?query=... — Search communities

### Lists
- GET /v1/twitter/lists/{list_id}/detail — Get list details
- GET /v1/twitter/lists/{list_id}/tweets — Get list tweets
- GET /v1/twitter/lists/{list_id}/search_tweets?query=... — Search in list

### Trends & Geo
- GET /v1/twitter/trends/ — Get trending topics
- GET /v1/twitter/trends/place/{woeid} — Get location trends
- GET /v1/twitter/geo/search?query=... — Search places
- GET /v1/twitter/geo/places/{place_id} — Get place details

### Spaces
- GET /v1/twitter/spaces/{space_id} — Get Space details
- GET /v1/twitter/spaces/broadcast/{broadcast_id} — Get broadcast

### Stream Monitors (real-time)
- POST /v1/twitter/stream/monitors — Create monitor (body: name, usernames[])
- GET /v1/twitter/stream/monitors — List monitors
- GET /v1/twitter/stream/monitors/{id} — Get monitor
- PATCH /v1/twitter/stream/monitors/{id} — Update (status: active/paused)
- DELETE /v1/twitter/stream/monitors/{id} — Delete monitor

### Filter Rules (query-based monitoring)
- POST /v1/twitter/filter-rules — Create rule (body: tag, query, interval_seconds)
- GET /v1/twitter/filter-rules — List rules
- GET /v1/twitter/filter-rules/{id} — Get rule
- PATCH /v1/twitter/filter-rules/{id} — Update rule
- DELETE /v1/twitter/filter-rules/{id} — Delete rule
- POST /v1/twitter/filter-rules/validate — Validate query syntax

---

## Vinted API (8 endpoints)

- GET /v1/vinted/search?query=...&market=fr&page=1&per_page=20 — Search items
- GET /v1/vinted/items/{item_id}?market=fr — Get item details
- GET /v1/vinted/users/{user_id}?market=fr — Get user profile
- GET /v1/vinted/users/{user_id}/items?market=fr — Get user's items
- GET /v1/vinted/brands?keyword=...&market=fr — Search brands
- GET /v1/vinted/colors?market=fr — List colors
- GET /v1/vinted/statuses?market=fr — List item conditions
- GET /v1/vinted/markets — List supported markets

Supported markets: fr, de, uk, us, es, it, nl, be, at, pl, pt, cz, lt, and more.

---

## Web Scraping API (6 endpoints)

- POST /v1/web/scrape — Scrape URL (body: url, render_js, return_format, proxy_country)
- POST /v1/web/detect — Detect anti-bot protection (body: url) — 1 credit
- POST /v1/web/screenshot — Take screenshot (body: url, full_page, width, height)
- POST /v1/web/extract — Extract data (body: url, ai_query, extract_rules)
- POST /v1/web/batch — Batch scrape (body: urls[])
- GET /v1/web/batch/{job_id} — Get batch status

---

## Pricing

- Twitter: 1 credit per call
- Vinted: 1 credit per call
- Web scraping: 1-10 credits (depends on JS rendering, anti-bot complexity)
- 1,000 free credits on signup
- Plans: https://scrapebadger.com/pricing

## Rate Limits

Per API key. Check X-RateLimit-Remaining response header.