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

# Run extraction

`POST /extractions`

## Query parameters

- `dry_run` boolean

## Request body

- ExtractionRequest — One synchronous estimate or asynchronous extraction request.
  - `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.
  - `targetTweetIds` string[] — Tweet IDs processed as one collection job.
  - `targetUsernames` string[] — Usernames processed as one collection job.
  - `targetCommunityIds` string[] — Community IDs processed as one collection job.
  - `targetListIds` string[] — List IDs processed as one collection job.
  - `searchQueries` string[] — Search queries processed as one collection job.
  - `targets` ExtractionMixedTarget[] — Mixed targets auto-routed within one job.
    - union — One auto-routed target in a mixed Tweet collection.
      - string — X URL, numeric Tweet ID, @username, kind:value target, or search.
      - object
        - `kind` 'favoriters' | 'list' | 'profile' | 'profile_likes' | 'profile_media' | 'profile_replies' | 'quotes' | 'replies' | 'retweeters' | 'search' | 'thread' | 'tweet', required
        - `value` string, required
  - `relationTargets` ExtractionRelationTarget[] — Profile relations processed within one job.
    - `relation` 'community_members' | 'followers' | 'following' | 'list_followers' | 'list_members' | 'verified_followers', required
    - `value` string, required
  - `queryType` 'Latest' | 'Top' | 'Both' — Search ranking applied to every query.
  - `maxItemsPerTarget` integer — Maximum results collected for each target.
  - `maxPagesPerTarget` integer — Reply pages collected for each target.
  - `startCursor` string — Resume one reply target from this cursor.
  - `dedupeAcrossTargets` boolean — Merge duplicate results across collection targets.
  - `dedupeMode` 'none' | 'first' | 'merge' — Keep target duplicates, first rows, or merged overlap.
  - `overlapMode` boolean — Shortcut for dedupeMode=merge.
  - `includeSearchTerms` boolean — Add matching search terms to collection metadata.
  - `includeTargetMetadata` boolean — Add source target metadata to each result.
  - `collectionStrategy` 'auto' | 'complete' | 'direct' | 'search' | 'thread' — Reply collection strategy.
  - `scope` 'all' | 'direct' | 'nested' — Reply depth scope.
  - `maxDepth` integer — Maximum nested reply depth.
  - `sort` 'relevance' | 'latest' | 'oldest' | 'likes' — Reply result order.
  - `excludeOriginalAuthor` boolean — Exclude replies from the source author.
  - `includeOriginalPost` boolean — Include the source post in reply results.
  - `hasMediaOnly` boolean — Return only replies with media.
  - `sinceTime` union — Reply start time as ISO 8601 or Unix seconds.
    - string, date-time
    - integer
  - `untilTime` union — Reply end time as ISO 8601 or Unix seconds.
    - string, date-time
    - integer
  - `minViews` integer — Minimum Tweet view count.
  - `minBookmarks` integer — Minimum Tweet bookmark count.
  - `maxLikes` integer — Maximum Tweet like count.
  - `maxRetweets` integer — Maximum Tweet repost count.
  - `maxReplies` integer — Maximum Tweet reply count.
  - `maxQuotes` integer — Maximum Tweet quote count.
  - `blueVerifiedOnly` boolean — Return only Blue-verified Tweet authors.
  - `cardName` string — Match the Tweet card name.
  - `source` string — Match the source application.
  - `excludeSource` string — Exclude a source application.
  - `geocode` string — Match latitude, longitude, and radius.
  - `sinceId` string — Return Tweets newer than this Tweet ID.
  - `maxId` string — Return Tweets older than this Tweet ID.
  - `near` string — Match a place name.
  - `within` string — Set the radius for the near filter.
  - `withinTime` string — Match Tweets inside a recent time window.
  - `nativeRetweets` boolean — Only return native reposts.
  - `safe` boolean — Enable the safe-search filter.
  - `news` boolean — Only return news results.
  - `minFollowers` integer — Minimum follower count for profile results.
  - `maxFollowers` integer — Maximum follower count for profile results.
  - `minFollowing` integer — Minimum following count for profile results.
  - `maxFollowing` integer — Maximum following count for profile results.
  - `minPosts` integer — Minimum post count for profile results.
  - `maxPosts` integer — Maximum post count for profile results.
  - `minAccountAgeDays` integer — Minimum profile age in days.
  - `verifiedType` string — Exact profile verification type.
  - `hasWebsite` boolean — Require a profile website.
  - `hasLocation` boolean — Require a profile location.
  - `bioContains` string — Bio terms separated by commas or lines.
  - `locationContains` string — Required profile location text.
  - `usernameContains` string — Required username text.
  - `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.

---

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