references/comparison.md
---
name: twitter-api-comparison
description: How fetcher.sh's Twitter/X endpoints compare to the official X API and a self-hosted headless-browser scraper, qualitative and scoped to what each actually does.
---
# Twitter / 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, tweets, 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
tweet 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: twitter-api-endpoints
description: Full parameter reference for every Twitter/X endpoint on twitter.fetcher.sh — path params, query params, required flags, and enum values, straight from the live OpenAPI contract.
---
# Twitter / X — full endpoint reference
Base URL: `https://twitter.fetcher.sh`. 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.
## Tweets
| Endpoint | Params |
| --- | --- |
| `/api/tweet/{id}` | none |
| `/api/tweet/{id}/replies` | `cursor`? |
| `/api/tweet/{id}/retweeters` | `cursor`? |
`{id}` is the tweet's numeric status ID (the number in a tweet URL). Treat it
as a string — it can exceed `Number.MAX_SAFE_INTEGER`, so parsing it as a JS
number silently corrupts it.
## 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 a `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 tweet 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: twitter-api-faq
description: Frequently asked questions about the Twitter/X API on fetcher.sh — search, followers, monitoring, and rate limits, answered with exact endpoints.
---
# Twitter / X API alternative — FAQ
## Getting started
### Do I need a Twitter/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 tweets 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 tweets with media or links?
Yes, using X's own operators inside `query`: `filter:media` for tweets with
images/video, `filter:links` for tweets 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 tweets 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 a Twitter List's tweets or members?
`GET /api/list/{id}/tweets` and `GET /api/list/{id}/members`, where `{id}` is
the numeric list ID from a `x.com/i/lists/{id}` URL.
## Tweets and engagement
### What's the cheapest way to look up one specific tweet I already have the ID for?
`GET /api/tweet/{id}` — $0.002/call, the cheapest endpoint on this host.
### How do I get replies to a specific tweet, not the whole thread?
`GET /api/tweet/{id}/replies`. This returns the reply set for that tweet
specifically, separate from `/api/user/{id}/replies` (a user's own reply
activity across tweets).
### Can I get quote tweets for a given tweet?
There's no dedicated quote-tweets endpoint on this host — only
`/api/tweet/{id}/replies` (replies) and `/api/tweet/{id}/retweeters` (who
retweeted). If you need quote tweets 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 tweets?
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 tweet 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 `twitter-api` cover both "Twitter" and "X" branding?
Yes — this skill and its sibling [`x-api`](../../x-api/SKILL.md) hit
the exact same host and endpoints; `x-api` just leads with "X" 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: twitter-api-scenarios
description: Worked curl examples for every Twitter/X endpoint on twitter.fetcher.sh, one per endpoint, including pagination.
---
# Twitter / 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 tweets:**
```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"
```
## Tweets
**A single tweet:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789"
```
**Replies to a tweet:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789/replies"
```
**Who retweeted a tweet:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/tweet/1234567890123456789/retweeters"
```
## Lists and trends
**A Twitter List's members:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/list/1234567890/members"
```
**A Twitter List's tweets:**
```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: twitter-api
description: >-
A Twitter API alternative and X 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 tweets by keyword,
hashtag, or advanced operators (from:, to:, since:, until:, min_faves:,
filter:), scrape a Twitter/X profile by handle, pull a user's tweets,
replies, followers, or followings, fetch a single tweet with its replies or
retweeters, read a Twitter List's members or tweets, check trending topics
by country, or search for X accounts by name. Also covers Twitter data
pipelines, competitor monitoring, hashtag tracking, sentiment analysis
input, or follower export without the official X API's pricing tiers or
app-review process.
keywords:
- twitter
- x
- twitter-api
- x-api
- twitter-api-alternative
- x-api-alternative
- tweet-search
- social-media
- social-listening
- x402
- ai-agent
---
# Twitter / X API
A drop-in Twitter/X data source for agents: search tweets, 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 a Twitter/X search query, a handle, a tweet ID, or a list
ID, this is the skill.
Base URL: `https://twitter.fetcher.sh`
Also published as [`x-api`](../x-api/SKILL.md) — same host, same
endpoints, indexed under the "X" name too since agents and users refer to the
platform both ways.
## 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 tweets 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 tweet by ID | `GET /api/tweet/{id}` |
| See who retweeted a tweet | `GET /api/tweet/{id}/retweeters` |
| Read a Twitter List's tweets 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 | Tweets 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 tweet 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 tweet by ID |
| `/api/tweet/{id}/replies` | $0.005 | Replies to a tweet |
| `/api/tweet/{id}/retweeters` | $0.005 | Accounts that retweeted a tweet |
| `/api/list/{id}/members` | $0.005 | A Twitter List's member accounts |
| `/api/list/{id}/tweets` | $0.005 | A Twitter List's tweet 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 tweets, 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 tweet, its replies, and who retweeted 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"
```
**A Twitter List's members and tweets:**
```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": {
"twitter": {
"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: [`/twitter-search`](../../commands/twitter-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>