Sign in

v

latestOpenAPI 3.1.02026-08-09127104507.8 KB
Extractions

Run extraction

Run extraction.

post/api/v1/extractions

Query parameters

dry_runboolean

Return a cost estimate without creating or running an extraction.

Request body

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.

targetTweetIdstring
targetUsernamestring
targetCommunityIdstring

Required for community_post_extractor & community_search.

targetListIdstring

Required for list_follower_explorer, list_member_extractor & list_post_extractor.

targetSpaceIdstring

Required for space_explorer.

targetTweetIdsstring[]

Tweet IDs processed as one collection job.

targetUsernamesstring[]

Usernames processed as one collection job.

targetCommunityIdsstring[]

Community IDs processed as one collection job.

targetListIdsstring[]

List IDs processed as one collection job.

searchQueriesstring[]

Search queries processed as one collection job.

queryType'Latest' | 'Top' | 'Both'

Search ranking applied to every query.

maxItemsPerTargetinteger

Maximum results collected for each target.

maxPagesPerTargetinteger

Reply pages collected for each target.

startCursorstring

Resume one reply target from this cursor.

dedupeAcrossTargetsboolean

Merge duplicate results across collection targets.

dedupeMode'none' | 'first' | 'merge'

Keep target duplicates, first rows, or merged overlap.

overlapModeboolean

Shortcut for dedupeMode=merge.

includeSearchTermsboolean

Add matching search terms to collection metadata.

includeTargetMetadataboolean

Add source target metadata to each result.

collectionStrategy'auto' | 'complete' | 'direct' | 'search' | 'thread'

Reply collection strategy.

scope'all' | 'direct' | 'nested'

Reply depth scope.

maxDepthinteger

Maximum nested reply depth.

sort'relevance' | 'latest' | 'oldest' | 'likes'

Reply result order.

excludeOriginalAuthorboolean

Exclude replies from the source author.

includeOriginalPostboolean

Include the source post in reply results.

hasMediaOnlyboolean

Return only replies with media.

minViewsinteger

Minimum Tweet view count.

minBookmarksinteger

Minimum Tweet bookmark count.

maxLikesinteger

Maximum Tweet like count.

maxRetweetsinteger

Maximum Tweet repost count.

maxRepliesinteger

Maximum Tweet reply count.

maxQuotesinteger

Maximum Tweet quote count.

blueVerifiedOnlyboolean

Return only Blue-verified Tweet authors.

cardNamestring

Match the Tweet card name.

sourcestring

Match the source application.

excludeSourcestring

Exclude a source application.

geocodestring

Match latitude, longitude, and radius.

sinceIdstring

Return Tweets newer than this Tweet ID.

maxIdstring

Return Tweets older than this Tweet ID.

nearstring

Match a place name.

withinstring

Set the radius for the near filter.

withinTimestring

Match Tweets inside a recent time window.

nativeRetweetsboolean

Only return native reposts.

safeboolean

Enable the safe-search filter.

newsboolean

Only return news results.

minFollowersinteger

Minimum follower count for profile results.

maxFollowersinteger

Maximum follower count for profile results.

minFollowinginteger

Minimum following count for profile results.

maxFollowinginteger

Maximum following count for profile results.

minPostsinteger

Minimum post count for profile results.

maxPostsinteger

Maximum post count for profile results.

minAccountAgeDaysinteger

Minimum profile age in days.

verifiedTypestring

Exact profile verification type.

hasWebsiteboolean

Require a profile website.

hasLocationboolean

Require a profile location.

bioContainsstring

Bio terms separated by commas or lines.

locationContainsstring

Required profile location text.

usernameContainsstring

Required username text.

resultsLimitinteger

Maximum number of results to extract. When set, the extraction stops after reaching this limit.

searchQuerystring

Required for tweet_search_extractor & community_search.

fromUserstring

Filter by author username (tweet_search_extractor)

toUserstring

Filter replies sent to a username (tweet_search_extractor)

mentioningstring

Filter tweets mentioning a username (tweet_search_extractor)

languagestring

Language code filter (tweet_search_extractor)

sinceDatestring date

Start date YYYY-MM-DD (tweet_search_extractor)

untilDatestring date

End date YYYY-MM-DD (tweet_search_extractor)

mediaType'images' | 'videos' | 'gifs' | 'media' | 'links' | 'none'

Media type filter (tweet_search_extractor)

minFavesinteger

Minimum likes threshold (tweet_search_extractor)

minRetweetsinteger

Minimum retweets threshold (tweet_search_extractor)

minRepliesinteger

Minimum replies threshold (tweet_search_extractor)

minQuotesinteger

Minimum quote count threshold (tweet_search_extractor)

verifiedOnlyboolean

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)

exactPhrasestring

Exact phrase to match (tweet_search_extractor)

excludeWordsstring

Words or quoted phrases to exclude. Separate with spaces, commas, or lines. (tweet_search_extractor)

anyWordsstring

Words or quoted phrases where any one can match. Separate with spaces, commas, or lines. (tweet_search_extractor)

hashtagsstring

Hashtags separated by spaces, commas, or lines. (tweet_search_extractor)

cashtagsstring

Cashtags separated by spaces, commas, or lines. (tweet_search_extractor)

urlstring

URL substring or domain filter (tweet_search_extractor)

conversationIdstring

Conversation ID filter (tweet_search_extractor)

inReplyToTweetIdstring

Only replies to this tweet ID (tweet_search_extractor)

quotesOfTweetIdstring

Only quotes of this tweet ID (tweet_search_extractor)

retweetsOfTweetIdstring

Only retweets of this tweet ID (tweet_search_extractor)

listIdstring

Search within a list ID (tweet_search_extractor)

placestring

Search within a place ID (tweet_search_extractor)

placeCountrystring

Search within a country code (tweet_search_extractor)

pointRadiusstring

Geo point radius, e.g. -73.99 40.73 25mi (tweet_search_extractor)

boundingBoxstring

Geo bounding box, e.g. -74.1 40.6 -73.9 40.8 (tweet_search_extractor)

advancedQuerystring

Raw advanced search query appended as-is (tweet_search_extractor)

Example request

{
  "toolType": "follower_explorer",
  "targetTweetId": "1234567890",
  "targetUsername": "elonmusk",
  "targetCommunityId": "1500000000000000000",
  "targetListId": "1234567890",
  "targetSpaceId": "1vOGwMdBqpwGB",
  "resultsLimit": 1000,
  "searchQuery": "AI trends 2025",
  "fromUser": "nasa",
  "toUser": "openai",
  "mentioning": "example_user",
  "language": "en",
  "sinceDate": "2025-01-01",
  "untilDate": "2025-12-31",
  "mediaType": "images",
  "minFaves": 10,
  "minRetweets": 5,
  "minReplies": 3,
  "minQuotes": 2,
  "replies": "include",
  "retweets": "exclude",
  "quotes": "include",
  "exactPhrase": "artificial intelligence",
  "excludeWords": "spam",
  "anyWords": "ChatGPT AI model",
  "hashtags": "#AI startups",
  "cashtags": "$TSLA $NVDA",
  "url": "example.com",
  "conversationId": "1234567890",
  "inReplyToTweetId": "1234567890",
  "quotesOfTweetId": "1234567890",
  "retweetsOfTweetId": "1234567890",
  "listId": "1234567890",
  "place": "96683cc9126741d1",
  "placeCountry": "US",
  "pointRadius": "-73.99 40.73 25mi",
  "boundingBox": "-74.1 40.6 -73.9 40.8",
  "advancedQuery": "min_faves:100"
}

Response

Dry-run estimate

allowedboolean required
creditsAvailablestring required
creditsRequiredstring required
estimatedResultsinteger required
resolvedXUserIdstring
sourcestring required