---
title: "X/Twitter Bulk Export"
method: POST
path: "/api/tools/x_extract"
tags: ["Intelligence"]
---

# X/Twitter Bulk Export

`POST /api/tools/x_extract`

## Request

- Base URL: `https://twitr.sh`
- URL: `https://twitr.sh/api/tools/x_extract`
- Auth: none declared. Required headers: `Idempotency-Key`

Bulk-export X/Twitter data as downloadable datasets: followers, following, repliers, quoters, reposters, likers, mentions, full threads, list and community members, spaces, or people/tweet search results — 23 extractors. Runs async: you get a claim check immediately and poll a free status URL for the download link. Billed per result.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `tool` 'follower_explorer' | 'following_explorer' | 'verified_follower_explorer' | 'post_extractor' | 'reply_extractor' | 'repost_extractor' | 'quote_extractor' | 'thread_extractor' | 'article_extractor' | 'favoriters' | 'mention_extractor' | 'user_likes' | 'user_media' | 'community_extractor' | 'community_moderator_explorer' | 'community_post_extractor' | 'community_search' | 'list_member_extractor' | 'list_post_extractor' | 'list_follower_explorer' | 'space_explorer' | 'people_search' | 'tweet_search_extractor', required: Which extractor to run.
  - `resultsLimit` integer, required: MANDATORY: max results extracted, billed per result.
  - `targetTweetId` string
  - `targetUsername` string
  - `targetCommunityId` string
  - `targetListId` string
  - `targetSpaceId` string
  - `searchQuery` string
  - `language` string
  - `sinceDate` string
  - `untilDate` string
  - `mediaType` 'images' | 'videos' | 'gifs' | 'media'
  - `minFaves` integer
  - `verifiedOnly` boolean

## Response `200`

Result dataset.

- object
  - `items` object[], required: Array of returned items. Shape varies per tool — see each tool's documentation.
  - `runId` string: Run ID for debugging/audit.
  - `duration` integer: Run duration in seconds.

## Other responses

- `202`: Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only).
- `400`: Bad request — missing resultsLimit or Idempotency-Key where required. Body is a Problem with `retryable:false` and a `hint`; never charged.
- `402`: Payment Required. Per-result reads require x402 upto on Base: authorize the maximum and pay only for delivered records, with a $0.0024 non-empty minimum and zero for empty results. Fixed-price operations may additionally offer exact x402 and MPP.
- `403`: Acting handle not connected to this wallet — connect it via /api/x-accounts/start first; never charged.
- `404`: Unknown tool path — GET /openapi.json for the valid list; never charged.
- `429`: Rate limited — `retryable:true`; retry unchanged after the Retry-After header; never charged.
- `500`: Unexpected handler error — inspect payment receipt before retrying.
- `502`: Upstream provider error — `retryable:true`; inspect payment receipt before retrying; prepaid operations may already be charged.
- `503`: Service capacity temporarily unavailable — `retryable:true`; retry later; never charged.

---

[API](https://skmtc.dev/twitr/apis/twitr-sh.md) · [All operations](https://skmtc.dev/twitr/apis/twitr-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/twitr/apis/twitr-sh/revisions/f6390fcee344?raw)