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 with...