---
title: "Run extraction"
method: POST
path: "/api/v1/extractions"
tags: ["Extractions"]
---

# Run extraction

`POST /api/v1/extractions`

Run extraction.

## Query parameters

- `dry_run` boolean

## Request body

- object
  - `toolType` 'article_extractor' | 'community_extractor' | 'community_moderator_explorer' | 'community_post_extractor' | 'community_search' | 'favoriters' | 'follower_explorer' | 'following_explorer' | 'list_follower_explorer' | 'list_member_extractor' | 'list_post_extractor' | 'mention_extractor' | 'people_search' | 'post_extractor' | 'quote_extractor' | 'reply_extractor' | 'repost_extractor' | 'space_explorer' | 'thread_extractor' | 'tweet_search_extractor' | 'user_likes' | 'user_media' | 'verified_follower_explorer', required — Identifier for the extraction tool used to run a job.
  - `targetTweetId` string
  - `targetUsername` string
  - `targetCommunityId` string — Required for community_post_extractor & community_search.
  - `targetListId` string — Required for list_follower_explorer, list_member_extractor & list_post_extractor.
  - `targetSpaceId` string — Required for space_explorer.
  - `resultsLimit` integer — Maximum number of results to extract. When set, the extraction stops after reaching this limit.
  - `searchQuery` string — Required for tweet_search_extractor & community_search.
  - `fromUser` string — Filter by author username (tweet_search_extractor)
  - `toUser` string — Filter replies sent to a username (tweet_search_extractor)
  - `mentioning` string — Filter tweets mentioning a username (tweet_search_extractor)
  - `language` string — Language code filter (tweet_search_extractor)
  - `sinceDate` string, date — Start date YYYY-MM-DD (tweet_search_extractor)
  - `untilDate` string, date — End date YYYY-MM-DD (tweet_search_extractor)
  - `mediaType` 'images' | 'videos' | 'gifs' | 'media' | 'links' | 'none' — Media type filter (tweet_search_extractor)
  - `minFaves` integer — Minimum likes threshold (tweet_search_extractor)
  - `minRetweets` integer — Minimum retweets threshold (tweet_search_extractor)
  - `minReplies` integer — Minimum replies threshold (tweet_search_extractor)
  - `minQuotes` integer — Minimum quote count threshold (tweet_search_extractor)
  - `verifiedOnly` boolean — Only verified authors (tweet_search_extractor)
  - `replies` 'include' | 'exclude' | 'only' — Reply mode (tweet_search_extractor)
  - `retweets` 'include' | 'exclude' | 'only' — Retweet mode (tweet_search_extractor)
  - `quotes` 'include' | 'exclude' | 'only' — Quote mode (tweet_search_extractor)
  - `exactPhrase` string — Exact phrase to match (tweet_search_extractor)
  - `excludeWords` string — Words or quoted phrases to exclude. Separate with spaces, commas, or lines. (tweet_search_extractor)
  - `anyWords` string — Words or quoted phrases where any one can match. Separate with spaces, commas, or lines. (tweet_search_extractor)
  - `hashtags` string — Hashtags separated by spaces, commas, or lines. (tweet_search_extractor)
  - `cashtags` string — Cashtags separated by spaces, commas, or lines. (tweet_search_extractor)
  - `url` string — URL substring or domain filter (tweet_search_extractor)
  - `conversationId` string — Conversation ID filter (tweet_search_extractor)
  - `inReplyToTweetId` string — Only replies to this tweet ID (tweet_search_extractor)
  - `quotesOfTweetId` string — Only quotes of this tweet ID (tweet_search_extractor)
  - `retweetsOfTweetId` string — Only retweets of this tweet ID (tweet_search_extractor)
  - `listId` string — Search within a list ID (tweet_search_extractor)
  - `place` string — Search within a place ID (tweet_search_extractor)
  - `placeCountry` string — Search within a country code (tweet_search_extractor)
  - `pointRadius` string — Geo point radius, e.g. -73.99 40.73 25mi (tweet_search_extractor)
  - `boundingBox` string — Geo bounding box, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)
  - `advancedQuery` string — Raw advanced search query appended as-is (tweet_search_extractor)

## Response `200`

Dry-run estimate

- object
  - `allowed` boolean, required
  - `creditsAvailable` string, required
  - `creditsRequired` string, required
  - `estimatedResults` integer, required
  - `resolvedXUserId` string
  - `source` string, required

## Other responses

- `202` — Extraction started
- `400` — Invalid input
- `401` — Unauthenticated
- `402` — Payment required. Fixed-price direct MPP requests return a Machine Payments Protocol problem document and a WWW-Authenticate challenge. Authenticated X data requests return balances and explicit Stripe checkout-creation actions. Guest paid-read keys receive only the accountless guest top-up action. Direct MPP challenges also advertise the Stripe wallet action. Other authenticated endpoints return a legacy error shape. A failed request never creates checkout. Create checkout only after the user confirms a payment option.
- `404` — Not found
- `424` — Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.
- `429` — Xquik tier rate limit exceeded. The response includes a `Retry-After` header with the number of seconds to wait before retrying.
- `502` — Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.
- `default` — Unexpected error.

---

[API](https://skmtc.net/xquik-dev/apis/xquik-api-2.md) · [All operations](https://skmtc.net/xquik-dev/apis/xquik-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api-2/versions/c70f0e286159/schema)