x-twitter-research

X research — bulk exports

Extractions run asynchronously: the call returns a claim check, you poll, and you get a download URL — not inline rows. That's deliberate; a 5,000-row dataset would swamp context.

Run one

POST https://twitr.sh/api/tools/x_extract
Idempotency-Key: <uuid>
{ "tool": "follower_explorer", "targetUsername": "vercel", "resultsLimit": 500 }

→ { "snapshot_id": "sd_…", "status": "pending", "status_url": "/api/snapshots/sd_…" }

Then poll (free, wallet-signed) until ready:

GET https://twitr.sh/api/snapshots/sd_…
→ { "status": "ready", "record_count": 500, "download_url": "https://…" }

Picking the target field

The tool decides which target you must supply — getting this wrong is the most common error:

Target field	Used by
targetUsername	follower / following / verified-follower / post / mention / likes / media
targetTweetId	reply / repost / quote / thread / article / favoriters
targetCommunityId	community members / moderators / posts
targetListId	list members / followers
targetSpaceId	space extractors
searchQuery	people_search, tweet_search_extractor

Gotchas

• resultsLimit is mandatory and it is the price. Billed per returned record at ~$0.0012, so 5,000 records ≈ $6. Quote the cost before running, and confirm above ~$1.
• article_extractor bills 5× per record. Budget accordingly.
• Idempotency-Key is required. Retrying without the same key starts — and charges for — a second job.
• The response is a claim check, not data. Don't try to read rows from the create response.
• Don't poll in a tight loop. Hand the user the snapshot_id and check when they ask; spinning burns tokens for no benefit. Large jobs take minutes.
• When ready, the data is behind download_url. Fetch and summarise, or hand over the URL — never paste a large dataset into context.
• GET /api/snapshots lists every dataset this wallet has paid for, so past exports are free to re-find.