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

# Create extraction

`POST /api/v1/extractions`

Starts an asynchronous extraction. Call waitUrl for a bounded wait, or poll statusUrl after pollAfterMs until job status is terminal.

## Query parameters

- `dry_run` boolean

## Headers

- `Idempotency-Key` string

## Request body

- ExtractionRequest — One estimate or extraction. Omit unrequested filters.
  - `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' | 'relevance' — Use Top for engagement. The relevance alias maps to Top.
  - `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 — Require Tweet cards whose name matches this value.
  - `source` string — Require Tweets from this source application.
  - `excludeSource` string — Drop Tweets from this source application.
  - `geocode` string — Restrict Tweets by latitude, longitude, and radius.
  - `sinceId` string — Require Tweets newer than this ID.
  - `maxId` string — Require Tweets older than this ID.
  - `near` string — Restrict Tweet search to this place name.
  - `within` string — Set the radius around the requested place.
  - `withinTime` string — Restrict Tweets to this recent time window.
  - `nativeRetweets` boolean — Require native repost results.
  - `safe` boolean — Apply safe-search filtering to Tweet results.
  - `news` boolean — Require news-classified Tweet 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 unique results to emit. Billing follows emitted results, not this upper bound.
  - `searchQuery` string — Required for tweet_search_extractor & community_search. Passed unchanged.
  - `fromUser` string — Filter by author username (tweet_search_extractor)
  - `toUser` string — Replies to this username (tweet_search_extractor).
  - `mentioning` string — Mentions this username (tweet_search_extractor).
  - `language` string — Only when requested (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' — Choose whether tweet search includes, excludes, or isolates replies.
  - `retweets` 'include' | 'exclude' | 'only' — Choose whether tweet search includes, excludes, or isolates reposts.
  - `quotes` 'include' | 'exclude' | 'only' — Choose whether tweet search includes, excludes, or isolates quotes.
  - `exactPhrase` string — Exact phrase to match (tweet_search_extractor)
  - `excludeWords` string — Excluded terms or phrases (tweet_search_extractor).
  - `anyWords` string — Any matching term or phrase (tweet_search_extractor).
  - `hashtags` string — Matching hashtags (tweet_search_extractor).
  - `cashtags` string — Matching cashtags (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

- ExtractionEstimate — Free credit estimate. It never creates a job or charges.
  - `allowed` boolean, required — Whether the balance covers the full estimate.
  - `creditsAvailable` string, required
  - `creditsRequired` string, required
  - `estimatedResults` integer, required — Credit calculation row count, not source availability.
  - `resolvedXUserId` string
  - `source` 'followers' | 'following' | 'collection' | 'paginationCap' | 'posts' | 'quoteCount' | 'replyCount' | 'resultsLimit' | 'retweetCount' | 'unknown', required

## Other responses

- `202` — Extraction started. Location identifies its result URL.
- `400` — Invalid input
- `401` — Unauthenticated
- `402` — Payment required. MPP reads include `WWW-Authenticate`. Authenticated reads include balances and checkout; a failed request never creates checkout. Guest keys offer top-up.
- `404` — Not found
- `409` — Idempotency-Key was reused with another request.
- `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.

## Changes

- **2026-08-25** `21827353271b` — 1 breaking, 6 warning, 4 info
  - the `status` response property const value `running` was removed for the status `202`
  - the `resultsLimit` request property's min was set to `1.00`
  - added the new `canceled` enum value to the `status` response property for the response status `202`
  - added the new `completed` enum value to the `status` response property for the response status `202`
  - …7 more
- **2026-08-24** `d6cb34aefa9f` — 2 info
  - added the required property `pollAfterMs` to the response with the `202` status
  - added the required property `statusUrl` to the response with the `202` status
- **2026-08-23** `dc5ab8bc994e` — 10 warning, 1 info
  - added the new `collection` enum value to the `source` response property for the response status `200`
  - added the new `followers` enum value to the `source` response property for the response status `200`
  - added the new `following` enum value to the `source` response property for the response status `200`
  - added the new `paginationCap` enum value to the `source` response property for the response status `200`
  - …7 more
- **2026-08-21** `18302a60cfee` — 1 breaking, 1 info
  - the `oneOf[subschema #4]/allOf[subschema #2]/` response's property type/format changed from ``/`` to `object`/`` for status `402`
  - added 'propertyNames' constraint to the `oneOf[subschema #4]/allOf[subschema #2]/` response property for the status `402`
- …earlier changes not shown

[Full history](https://skmtc.dev/xquik-dev/apis/xquik-api-2/changes/api/v1/extractions/post.md)

---

[API](https://skmtc.dev/xquik-dev/apis/xquik-api-2.md) · [All operations](https://skmtc.dev/xquik-dev/apis/xquik-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api-2/revisions/834c16fa45e8/schema)