references/comparison.md
---
name: x-scraper-comparison
description: How fetcher.sh's X (Twitter) endpoints compare to the official X API and a self-hosted headless-browser scraper, qualitative and scoped to what each actually does.
---
# X data access — comparing your options
Three ways to get X data programmatically. This is a qualitative comparison
of access models, not a pricing sheet — treat any specific competitor price
you see elsewhere as something to verify yourself, not something repeated
here.
## Official X API
- Requires a developer account, app review, and OAuth 2.0 or OAuth 1.0a
credentials before your first call.
- Sold in fixed monthly tiers with a pre-allocated post/read cap, not
pay-as-you-go — you pay for the tier whether you use it or not.
- Endpoint coverage and field availability vary by tier; some fields
(e.g. full-archive search) are gated to the highest tiers.
- Best fit when you're building a product that needs guaranteed uptime SLAs,
X's own ToS-sanctioned access, and predictable monthly billing.
## Headless-browser scraper (self-hosted)
- No API key at all — you drive a real browser (Playwright/Puppeteer) against
x.com and parse the DOM or intercepted XHR responses yourself.
- You own and pay for the infrastructure (proxies, browser fleet, CAPTCHA
handling, session/cookie rotation) and you own the maintenance burden when
X changes its frontend.
- No fixed per-call price — cost is your compute + proxy bill, which scales
with volume and gets more expensive as anti-bot defenses tighten.
- Best fit when you need something the same subdomain-per-service model
doesn't expose yet, or you're already running scraping infra for other
sites and want one more target.
## fetcher.sh (`twitter.fetcher.sh`)
- No developer account, no OAuth, no app review — authenticate to
`twitter.fetcher.sh` itself with a Bearer key or an x402 payment.
- Pay per call: $0.002–$0.005/request depending on endpoint (see
[`endpoints.md`](endpoints.md)), no monthly minimum, no tier to outgrow.
- Fixed endpoint set (search, profiles, posts, timelines, followers, lists,
trends) mirrored across 11 services with the same JSON envelope and the
same MCP tool names — one integration pattern reused everywhere.
- Read-only, on-demand: no webhooks, no streaming, no writes/posting. If you
need "notify me when X happens," you poll on a schedule yourself.
- Best fit when you want ad-hoc or moderate-volume reads without upfront
account setup, and you're fine treating X as one of several data sources
behind the same MCP/REST pattern.
## Named providers to benchmark against
Don't take any provider's framing (including this one) at face value — pull
the same data from each and compare the actual response. A few concrete
starting points, current as of this writing (verify pricing and limits
yourself before deciding, since all three change their terms independently
of this repo):
| Provider | Docs | What to check |
| --- | --- | --- |
| Official X API | [docs.x.com/x-api/overview](https://docs.x.com/x-api/overview) | Does your required field or date range need first-party access? |
| Apify Tweet Scraper | [apify.com/apidojo/tweet-scraper](https://apify.com/apidojo/tweet-scraper) | Does an Actor-based, dataset/export-oriented workflow fit your pipeline better than direct REST? |
| Bright Data X (Twitter) Scraper API | [docs.brightdata.com/datasets/scrapers/twitter/introduction](https://docs.brightdata.com/datasets/scrapers/twitter/introduction) | Do you need bulk async collection (1000s of URLs) more than single-call reads? |
## Build your own comparison
Pick one fixed test — the same handle, the same search query, the same post
ID — and run it against fetcher.sh and whichever provider above is a
candidate. Record, per provider:
- Which required fields actually came back (not just which fields the docs
promise)
- Cost for the exact rows you kept, after discarding anything you didn't need
- Time from request to usable JSON
- What happens on the second and third call — does pagination stay stable,
does a cached/rate-limited path kick in, does the price change
A five-minute test like this is worth more than any comparison table,
including this one.
## Quick decision guide
| Need | Pick |
| --- | --- |
| Building a product needing an official ToS-covered integration with SLAs | Official X API |
| One-off script, no account setup, pay only for what you call | fetcher.sh |
| Already running scraping infra, need something fetcher.sh doesn't expose | Headless browser |
| Same integration pattern across X, TikTok, Instagram, Reddit, etc. | fetcher.sh |
## See also
- [`endpoints.md`](endpoints.md) — full parameter reference
- [`scenarios.md`](scenarios.md) — worked `curl` examples
- [`faq.md`](faq.md) — task-oriented "how do I..." answers
references/endpoints.md
---
name: x-scraper-endpoints
description: Full parameter reference for every X (Twitter) endpoint on twitter.fetcher.sh — path params, query params, required flags, and enum values, straight from the live OpenAPI contract.
---
# X — full endpoint reference
Base URL: `https://twitter.fetcher.sh` (same host X used before the rebrand —
fetcher.sh never moved it). All 15 endpoints are `GET`, authenticated with
either `Authorization: Bearer bby_live_...` (credits) or an x402 payment —
see [`SKILL.md`](../SKILL.md) for the payment flow. Path parameters are
written as `{param}`; substitute the real value. `?` marks an optional query
param.
This file lists every parameter that exists. It does not describe response
fields — the response shape is generated at request time from the live
handlers, so the authoritative machine-readable version is always
[`/openapi.json`](https://twitter.fetcher.sh/openapi.json). Treat any field
name you haven't seen in an actual response as unverified.
## Search
| Endpoint | Params |
| --- | --- |
| `/api/search` | `query` (required) · `sort`? (`Latest`, `Top`) · `cursor`? |
| `/api/search/users` | `query` (required) · `cursor`? |
`query` on `/api/search` is passed straight to X's own search parser — every
operator X supports (`from:`, `to:`, `since:`, `until:`, `min_faves:`,
`min_retweets:`, `filter:`, `-filter:`) works unmodified.
## Profiles
| Endpoint | Params |
| --- | --- |
| `/api/handle/{handle}` | none |
| `/api/handle/{handle}/about` | none |
| `/api/user/{id}` | none |
`{handle}` takes the `@username` without the `@`. `{id}` is the numeric user
ID returned by the handle lookup — endpoints below that take `{id}` need this
value, not the handle.
## Timelines and relationships
| Endpoint | Params |
| --- | --- |
| `/api/user/{id}/tweets` | `cursor`? |
| `/api/user/{id}/replies` | `cursor`? |
| `/api/user/{id}/followers` | `cursor`? |
| `/api/user/{id}/followings` | `cursor`? |
All four paginate with an opaque `cursor` — pass back exactly what the
previous response returned, never construct or decode it.
## Posts
| Endpoint | Params |
| --- | --- |
| `/api/tweet/{id}` | none |
| `/api/tweet/{id}/replies` | `cursor`? |
| `/api/tweet/{id}/retweeters` | `cursor`? |
`{id}` is the post's numeric status ID (the number in an X URL). Treat it as
a string — it can exceed `Number.MAX_SAFE_INTEGER`, so parsing it as a JS
number silently corrupts it. The path segment is still `tweet` — the API
predates the "post" rename and fetcher.sh mirrors the live route as-is.
## Lists and trends
| Endpoint | Params |
| --- | --- |
| `/api/list/{id}/members` | `cursor`? |
| `/api/list/{id}/tweets` | `cursor`? |
| `/api/trends` | `country` (required) |
`{id}` for lists is the numeric list ID from an `x.com/i/lists/{id}` URL.
`country` on `/api/trends` takes a country name (e.g. `United States`), not
an ISO code.
## Pricing
Every endpoint above is $0.005/call except `/api/tweet/{id}`, which is
$0.002/call — the cheapest way to resolve a single post ID you already have.
## See also
- [`scenarios.md`](scenarios.md) — one worked `curl` per endpoint
- [`faq.md`](faq.md) — task-oriented "how do I..." answers
- [`comparison.md`](comparison.md) — fetcher.sh vs. the official X API vs. a browser scraper
references/faq.md
---
name: x-scraper-faq
description: Frequently asked questions about scraping X (Twitter) data with fetcher.sh — search, followers, monitoring, and rate limits, answered with exact endpoints.
---
# X API alternative — FAQ
## Getting started
### Do I need an X developer account or OAuth app?
No. `twitter.fetcher.sh` is a separate read-only proxy — you authenticate to
*it*, not to X. No developer account, no app review, no OAuth flow.
### What payment methods are supported?
Prepaid credits (`Authorization: Bearer bby_live_...`) or x402 micropayments
in USDC on Base, Polygon, Arbitrum, Monad, or Solana — see the [`fetcher`
skill](../../fetcher/SKILL.md) for setup.
### Is there a rate limit?
No fixed per-minute cap enforced by fetcher.sh itself — cost is the limiter:
each call is billed individually (credits or x402), so throughput is bounded
by your budget and by the upstream page latency, not by a quota.
## Search
### How do I search posts by keyword?
`GET /api/search?query=...` on `twitter.fetcher.sh`. `query` accepts the same
advanced operators X's own search bar does (`from:`, `since:`, `min_faves:`,
`filter:`, etc.) — see [`scenarios.md`](scenarios.md).
### How do I search only a date range?
Add `since:YYYY-MM-DD` and `until:YYYY-MM-DD` to the `query` string — there's
no separate `startDate`/`endDate` param, it's all one search string.
### Can I filter search results to only posts with media or links?
Yes, using X's own operators inside `query`: `filter:media` for posts with
images/video, `filter:links` for posts containing a URL. Combine with other
operators the same way you'd combine them in X's own search bar.
### Can I look up multiple posts in one call?
No — `/api/tweet/{id}` takes one ID per request. There's no batch/bulk
lookup endpoint on this host; loop over IDs if you need several.
## Profiles, followers, and lists
### How do I get a user's follower list?
`GET /api/user/{id}/followers`, where `{id}` is the numeric ID from
`GET /api/handle/{handle}`. Paginate with the returned `cursor` until the
response stops returning one.
### Can I export followers to CSV directly?
Not server-side. Fetcher.sh returns JSON; paginate through
`/api/user/{id}/followers` and write the pages to a CSV yourself. There's no
built-in export job.
### How do I get an X List's posts or members?
`GET /api/list/{id}/tweets` and `GET /api/list/{id}/members`, where `{id}` is
the numeric list ID from an `x.com/i/lists/{id}` URL.
## Posts and engagement
### What's the cheapest way to look up one specific post I already have the ID for?
`GET /api/tweet/{id}` — $0.002/call, the cheapest endpoint on this host. The
path is still `tweet`, not `post` — fetcher.sh mirrors the live API route
name as-is.
### How do I get replies to a specific post, not the whole thread?
`GET /api/tweet/{id}/replies`. This returns the reply set for that post
specifically, separate from `/api/user/{id}/replies` (a user's own reply
activity across posts).
### Can I get quote posts for a given post?
There's no dedicated quote-posts endpoint on this host — only
`/api/tweet/{id}/replies` (replies) and `/api/tweet/{id}/retweeters` (who
reposted). If you need quote posts specifically, that's a gap in the current
endpoint set, not something to work around with a different param.
## Monitoring and discovery
### How do I monitor a hashtag or account for new posts?
There's no webhook or streaming endpoint. Poll `/api/search` (for a hashtag
or `from:` query) on a schedule — e.g. a cron job every few minutes — and
diff against the post IDs you've already seen.
### How do I find trending topics?
`GET /api/trends?country=United%20States`. `country` takes a full country
name, not an ISO code.
### Can an agent discover these endpoints without reading this file?
Yes — `twitter.fetcher.sh/mcp` exposes `search_endpoints`, `describe_endpoint`,
and `fetch_data` as MCP tools, so an MCP-connected agent can explore the API
live instead of relying on this document.
### Where's the authoritative schema if this doc goes stale?
`https://twitter.fetcher.sh/openapi.json` and `https://twitter.fetcher.sh/llms.txt`
are generated from the live route handlers and always match production.
## Naming
### Does this skill cover both "X" and "Twitter" branding?
Yes — this skill and its sibling
[`twitter-scraper`](../../twitter-scraper/SKILL.md) hit the exact same host
and endpoints; `twitter-scraper` leads with "Twitter" wording so agents
searching either term find a match.
## See also
- [`endpoints.md`](endpoints.md) — full parameter reference
- [`scenarios.md`](scenarios.md) — worked `curl` examples
- [`comparison.md`](comparison.md) — fetcher.sh vs. the official X API vs. a browser scraper
references/scenarios.md
---
name: x-scraper-scenarios
description: Worked curl examples for every X (Twitter) endpoint on twitter.fetcher.sh, one per endpoint, including pagination.
---
# X — full scenario cookbook
Every call below assumes:
```bash
export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx"
```
Swap the `curl -H "Authorization: Bearer $FETCHER_API_KEY"` prefix for a bare
`curl` if you're paying per call with x402 instead — see the [`fetcher`
skill](../../fetcher/SKILL.md).
## Search
**Everything from one account, newest first:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=from:OpenAI" -G \
--data-urlencode "sort=Latest" \
"https://twitter.fetcher.sh/api/search"
```
**Between two dates:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=x402 since:2026-01-01 until:2026-02-01" -G \
"https://twitter.fetcher.sh/api/search"
```
**Popular posts only, replies excluded:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=ai agents min_faves:500 -filter:replies" -G \
--data-urlencode "sort=Top" \
"https://twitter.fetcher.sh/api/search"
```
**Next page of a search (reuse the `cursor` from the previous response):**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=ai agents" -G \
--data-urlencode "cursor=<cursor from previous response>" \
"https://twitter.fetcher.sh/api/search"
```
**Search accounts by name:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=climate scientist" -G \
"https://twitter.fetcher.sh/api/search/users"
```
## Profiles
**Resolve a profile by handle:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/handle/nasa"
```
**Extended about/bio info by handle:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/handle/nasa/about"
```
**Profile by numeric ID (once you have it from the handle lookup):**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/user/11348282"
```
## Timelines and relationships
**A user's posts:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/user/11348282/tweets"
```
**A user's replies:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/user/11348282/replies"
```
**A user's followers, paginated:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/user/11348282/followers"
# next page
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "cursor=<cursor from previous response>" -G \
"https://twitter.fetcher.sh/api/user/11348282/followers"
```
**Accounts a user follows:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/user/11348282/followings"
```
## Posts
**A single post:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789"
```
**Replies to a post:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789/replies"
```
**Who reposted a post:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789/retweeters"
```
## Lists and trends
**An X List's members:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/list/1234567890/members"
```
**An X List's posts:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/list/1234567890/tweets"
```
**Trending topics for a country:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "country=United States" -G \
"https://twitter.fetcher.sh/api/trends"
```
## See also
- [`endpoints.md`](endpoints.md) — full parameter reference
- [`faq.md`](faq.md) — task-oriented "how do I..." answers
- [`comparison.md`](comparison.md) — fetcher.sh vs. the official X API vs. a browser scraper
SKILL.md
---
name: x-scraper
description: >-
An X API alternative and Twitter API alternative on fetcher.sh — pay-per-call
in USDC via x402, or prepaid credits with a Bearer key, no OAuth and no
developer application. Use when the user wants to search X posts by
keyword, hashtag, or advanced operators (from:, to:, since:, until:,
min_faves:, filter:), scrape an X/Twitter profile by handle, pull a user's
posts, replies, followers, or followings, fetch a single post with its
replies or reposters, read an X List's members or posts, check trending
topics by country, or search for X accounts by name. Also covers building an
X data pipeline, social listening, competitor monitoring, hashtag tracking,
or follower export without the official X API's pricing tiers or
app-review process.
keywords:
- x
- twitter
- x-api
- twitter-api
- x-api-alternative
- twitter-api-alternative
- x-data-api
- x-scraper
- social-media
- social-listening
- x402
- ai-agent
---
# X (Twitter) Data API
A drop-in X data source for agents: search posts, resolve profiles, pull
timelines and followers, read Lists, and check trends — all as one plain HTTP
GET, paid per call. No developer account, no app review, no OAuth handshake,
and no waiting on X's own API tiers or rate-limit approvals. If your task
mentions an X search query, a handle, a post/tweet ID, or a list ID, this is
the skill.
Base URL: `https://twitter.fetcher.sh` — the API host is still named
`twitter` (it predates the rebrand and matches what agents already search
for); everything below is current X data.
Also published as [`twitter-scraper`](../twitter-scraper/SKILL.md) — identical
endpoints, indexed under the "Twitter" name too since both are still in
everyday use.
## Quick reference
| | |
| --- | --- |
| Base URL | `https://twitter.fetcher.sh` |
| Auth | `Authorization: Bearer bby_live_...` or x402 (USDC) |
| Price | $0.002–$0.005/call |
| Endpoints | 15, all `GET` |
| MCP | `https://twitter.fetcher.sh/mcp` |
| Machine-readable | `/openapi.json` · `/llms.txt` · `/skill.md` |
## Which endpoint do I need?
| I want to... | Call |
| --- | --- |
| Search posts by keyword or operator (`from:`, `since:`, `min_faves:`, ...) | `GET /api/search` |
| Search accounts by name | `GET /api/search/users` |
| Look up a profile by @handle | `GET /api/handle/{handle}` |
| Get a user's followers or followings | `GET /api/user/{id}/followers` or `/followings` |
| Get a single post by ID | `GET /api/tweet/{id}` |
| See who reposted a post | `GET /api/tweet/{id}/retweeters` |
| Read an X List's posts or members | `GET /api/list/{id}/tweets` or `/members` |
| Check trending topics for a country | `GET /api/trends` |
Full param details for every row: [`references/endpoints.md`](references/endpoints.md).
## Authentication
Two ways to pay, same data — full mechanics in the [`fetcher`
skill](../fetcher/SKILL.md):
```bash
# 1. Prepaid credits (recommended — get a key at https://fetcher.sh/topup
# or via POST /api/credits/topup, see the fetcher skill)
export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/search?query=hello"
# 2. x402 pay-per-call — omit the header; a GET with no payment returns 402
# with machine-readable payment requirements (USDC on Base, Polygon,
# Arbitrum, Monad, or Solana). @x402/fetch signs and retries automatically.
```
Every response is `{ "status": number, "message": string, "data": ... }`; the
HTTP status mirrors `status`.
## Endpoints (15 — all GET, $0.005/call unless noted)
| Endpoint | Price | What it returns |
| --- | --- | --- |
| `/api/search` | $0.005 | Posts matching a query; supports X's advanced search operators |
| `/api/search/users` | $0.005 | Accounts matching a name/keyword query |
| `/api/handle/{handle}` | $0.005 | Profile by @handle |
| `/api/handle/{handle}/about` | $0.005 | Extended profile/about info by @handle |
| `/api/user/{id}` | $0.005 | Profile by numeric user ID |
| `/api/user/{id}/tweets` | $0.005 | A user's post timeline |
| `/api/user/{id}/replies` | $0.005 | A user's replies |
| `/api/user/{id}/followers` | $0.005 | A user's followers |
| `/api/user/{id}/followings` | $0.005 | Accounts a user follows |
| `/api/tweet/{id}` | **$0.002** | A single post by ID |
| `/api/tweet/{id}/replies` | $0.005 | Replies to a post |
| `/api/tweet/{id}/retweeters` | $0.005 | Accounts that reposted a post |
| `/api/list/{id}/members` | $0.005 | An X List's member accounts |
| `/api/list/{id}/tweets` | $0.005 | An X List's post feed |
| `/api/trends` | $0.005 | Trending topics for a country |
`{id}` / `{handle}` are path parameters — substitute the real value. Optional
query params (`cursor`, `sort`) paginate or reorder; only `query` (search) and
`country` (trends) are required elsewhere they appear.
## Scenarios
The query on `/api/search` goes straight to X's own search, so its operators
work as-is: `from:`, `to:`, `since:`, `until:`, `min_faves:`, `min_retweets:`,
`filter:`, `-filter:`.
**Everything from one account:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/search?query=from%3AOpenAI&sort=Latest"
```
**Between two dates:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=x402 since:2026-01-01 until:2026-02-01" -G \
"https://twitter.fetcher.sh/api/search"
```
**Popular posts only, replies excluded:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=ai agents min_faves:500 -filter:replies" -G \
--data-urlencode "sort=Top" \
"https://twitter.fetcher.sh/api/search"
```
**Search accounts by name:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "query=climate scientist" -G \
"https://twitter.fetcher.sh/api/search/users"
```
**Resolve a profile by handle, then pull its bio/about:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/handle/nasa"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/handle/nasa/about"
```
**A user's posts, replies, followers, or followings (by numeric ID from the
handle lookup above):**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/user/11348282/tweets"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/user/11348282/followers"
```
**A single post, its replies, and who reposted it:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789/replies"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789/retweeters"
```
**An X List's members and posts:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/list/1234567890/members"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/list/1234567890/tweets"
```
**Trending topics for a country:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/trends?country=United%20States"
```
## MCP
```json
{
"mcpServers": {
"x": {
"url": "https://twitter.fetcher.sh/mcp",
"headers": { "Authorization": "Bearer bby_live_..." }
}
}
}
```
Free: `search_endpoints`, `describe_endpoint`, `check_balance`. Paid:
`fetch_data` (any endpoint above), `topup_credits`, plus the named shortcut
`twitter_search`. Drop the `headers` block to pay per call with x402 instead —
see the [`fetcher` skill](../fetcher/SKILL.md) for the full flow.
## Errors
- `400` — missing/invalid parameter (message names it)
- `401` — unknown or rotated key
- `402` — payment required (x402 challenge) or `topup_required` (credits
exhausted)
- `404` — not a priced path
- No rate limits; no refunds on upstream failures (settlement precedes
delivery)
## Reference
- Deep dives: [`references/endpoints.md`](references/endpoints.md) (every
param) · [`references/scenarios.md`](references/scenarios.md) (one `curl`
per endpoint) · [`references/faq.md`](references/faq.md) ·
[`references/comparison.md`](references/comparison.md) (vs. the official
X API and a browser scraper)
- Task guides: [search tweets](../../task-guides/search-tweets.md) ·
[export followers](../../task-guides/export-twitter-followers.md)
- Slash command: [`/x-search`](../../commands/x-search.md)
- Full agent setup: <https://twitter.fetcher.sh/skill.md>
- OpenAPI 3.1 contract: <https://twitter.fetcher.sh/openapi.json>
- Condensed catalog: <https://twitter.fetcher.sh/llms.txt>
- Payment, credits, and MCP deep dive: [`fetcher` skill](../fetcher/SKILL.md)
- Site: <https://twitter.fetcher.sh>