Skip to main content
POST
Twitter scraping cost estimator & credit quote
Free. This endpoint does not consume credits.

Estimate Twitter API scraping cost

Request a free credit quote before starting any extraction. The response estimates results and required credits. It also checks your available credit balance. A quote never starts a scraping job. Use the same request fields for estimation and extraction. Keep toolType, target fields, filters, and resultsLimit unchanged. The quote then matches the job you run.

Match each scraping task

Other supported tools estimate likes, media, mentions, quotes, reposts, threads, Spaces, and articles. Use their matching target fields below.

Control the credit quote

resultsLimit defaults to 10,000. Set any positive integer for a different bound. The estimator adjusts creditsRequired for that projected count. Narrow tweet search estimates with dates, authors, languages, engagement thresholds, or media filters. Reuse those filters when creating the extraction. Changed filters can produce a different estimate. Post estimates use the 1,000-row cap. A protected profile returns 403 x_account_protected.

Read the estimate

When allowed is false, lower resultsLimit, narrow filters, or add credits. Then request another quote.

Headers

string
required
Your API key. Session cookie authentication is also supported. Generate a key from the dashboard.
string
required
Must be application/json.
The estimator accepts the same fields as Create Extraction.

Body

string
required
Extraction tool to run or estimate. See the endpoint’s tool list.

Single targets

string
Tweet ID for a tweet-centered extraction.
string
Username for an account-centered extraction. You may include @.
string
Community ID for a community extraction.
string
List ID for a list extraction.
string
Space ID for space_explorer.
string
Query for tweet_search_extractor, people_search or community_search. tweet_search_extractor adds the structured search fields, such as fromUser and minFaves, to this query. X searches up to 512 characters. A longer tweet or people search answers 400, counted with the added fields.

Collection targets

string[]
Process 1-10,000 Tweet IDs in one collection job.
string[]
Process 1-100 unique usernames in one job. tweet_search_extractor collects their posts.
string[]
Process 1-100 unique community IDs in one collection job.
string[]
Process 1-100 unique List IDs in one collection job.
string[]
Process 1-100 unique search queries in one collection job. Each follows the rules of searchQuery, its structured fields and 512-character limit included.
array
Process up to 10,000 mixed targets with automatic routing.
Each target accepts a supported string or { "kind": "...", "value": "..." }.
array
Process up to 100 profile relations in one collection job.
Each relation target uses { "relation": "...", "value": "..." }.

Collection controls

string
Search ranking. Use Latest, Top, or Both. Defaults to Latest.
integer
Maximum unique results to emit. Defaults to 10,000. Use any positive integer.
integer
Maximum results collected for each target. At least 1.
integer
Reply pages collected per target. Accepts 1-1,000.
string
Resume one reply target from this cursor.
boolean
Merge duplicates across targets. Defaults to true.
string
Duplicate handling. Use none, first, or merge.
boolean
Use dedupeMode=merge. Defaults to false.
boolean
Add matched search terms to collection metadata. Defaults to false.
boolean
Add source target metadata to each result. Defaults to true.
boolean
Add each user’s full profile at enrichmentData.profile. Applies to follower_explorer, following_explorer, verified_follower_explorer, people_search & repost_extractor. Jobs take longer. Defaults to false.

Reply collection

string
Collection strategy. Use auto, complete, direct, search, or thread.
string
Reply scope. Use all, direct, or nested. Defaults to all.
integer
Maximum nested reply depth. At least 1.
string
Sort order. Use relevance, latest, oldest, or likes.
boolean
Exclude replies from the source author. Defaults to false.
boolean
Include the source post. Defaults to false.
boolean
Return only replies with media. Defaults to false.
string | integer
Reply start time as ISO 8601 or Unix seconds.
string | integer
Reply end time as ISO 8601 or Unix seconds.

Tweet result filters

integer
Minimum Tweet view count.
integer
Minimum Tweet bookmark count.
integer
Maximum Tweet like count.
integer
Maximum Tweet repost count.
integer
Maximum Tweet reply count.
integer
Maximum Tweet quote count.
boolean
Return only Blue-verified Tweet authors. On a tool that returns users, return only profiles X marks as blue verified. Defaults to false.
string
X search no longer supports cardName, so a search with it finds no Tweets.
string
X search no longer supports source. An extraction with it answers 424 search_unavailable & charges nothing.
string
X search ignores excludeSource, so an extraction with it returns unfiltered rows. Its answers carry Deprecation & Sunset headers. From 2027-01-15 an extraction with it answers 424 search_unavailable & charges nothing.
string
X search no longer supports geocode. An extraction with it answers 424 search_unavailable & charges nothing.
string
Return Tweets whose IDs exceed this ID.
string
Return Tweets at or below this ID.
string
A place name. A country, such as United States, works like placeCountry & keeps Tweets tagged there. A city keeps Tweets about it.
string
X search no longer supports within. An extraction with it answers 424 search_unavailable & charges nothing. Use near alone.
string
Match Tweets inside a recent time window.
boolean
Return only native reposts. Defaults to false.
boolean
Enable safe search. Defaults to false.
boolean
X search no longer supports filter:news. An extraction with news set to true answers 424 search_unavailable & charges nothing.

Profile result filters

integer
Minimum profile follower count.
integer
Maximum profile follower count.
integer
Minimum profile following count.
integer
Maximum profile following count.
integer
Minimum profile post count.
integer
Maximum profile post count.
integer
Minimum profile age in days.
string
Match the exact profile verification type.
boolean
Require a profile website. Defaults to false.
boolean
Require a profile location. Defaults to false.
boolean
Require an email the profile publishes. Defaults to false.
boolean
Require an email outside free webmail, such as Gmail. Defaults to false.
string
Require an email at one of these comma-separated domains. Subdomains match.
string
Match any bio term, ignoring case. Separate terms with commas or lines.
string
Require matching profile location text.
string
Require matching username text.

Tweet search filters

These fields apply to tweet_search_extractor.
string
Match an author username without @.
string
Match replies sent to a username.
string
Match Tweets mentioning a username.
string
Match a language code, such as en.
string
Include Tweets on or after YYYY-MM-DD.
string
Include Tweets up to YYYY-MM-DD, a UTC day, inclusive, so its own Tweets count.
string
Media filter. Use images, videos, gifs, media, links, or none.
integer
Minimum like count.
integer
Minimum repost count.
integer
Minimum reply count.
integer
Minimum quote count.
boolean
Return only verified authors.
string
Reply mode. Use include, exclude, or only.
string
Repost mode. Use include, exclude, or only.
string
Quote mode. Use include, exclude, or only.
string
Match one exact phrase.
string
Exclude words or quoted phrases.
string
Match any listed word or quoted phrase.
string
Match hashtags separated by spaces, commas, or lines.
string
Match cashtags separated by spaces, commas, or lines.
string
Match a URL substring or domain.
string
Match a conversation ID.
string
Return only replies to this Tweet ID.
string
Return only quotes of this Tweet ID.
string
Return only reposts of this Tweet ID.
string
Search within a List ID.
string
Search within a place ID.
string
Search within a country code.
string
Set a geographic center and radius.
string
Set a geographic bounding box.
string
Append raw advanced search syntax.

Response

200 OK

boolean
Whether the extraction can proceed given the current credit balance.
string
Data source used for the estimate. It is collection, followers, following, paginationCap, quoteCount, replyCount, resultsLimit, retweetCount, or unknown.
number
Estimated number of results the extraction will return.
string
Credits this extraction will consume (stringified integer).
string
Credits available in your balance (stringified integer).
string
Resolved X user ID from count-based profile estimates.
When allowed is false, credits required exceed the available balance.

400 Invalid input

The request body is missing or malformed. Send toolType and its matching target field.

400 Invalid tool type

The toolType value is not one of the 23 supported tools.

401 Unauthenticated

Missing or invalid API key.

402 Insufficient credits

The available balance cannot cover the estimate. Possible error values include no_subscription, subscription_inactive, no_credits, and insufficient_credits.

404 Not found

The target tweet does not exist, was deleted, or the ID is invalid.
The target user does not exist or is suspended.

429 Rate limited

Wait for the Retry-After value before requesting another estimate.

Decision handoff

A 200 OK response is a quote. It starts no extraction. Store the estimate with the request you plan to run.

Allowed run

When allowed is true, send the same toolType, target fields, filters, and resultsLimit to Create Extraction. Store the returned job ID from that 202 Accepted receipt.

Blocked run

When allowed is false, lower resultsLimit, narrow the target or filters, or add credits before calling Create Extraction.

Source signal

Store source so operators know whether the estimate came from replyCount, followers, resultsLimit, paginationCap, or another supported count.

Audit fields

Store estimatedResults, creditsRequired, creditsAvailable, allowed, and source with the planned extraction request.
Call this endpoint before every extraction. It catches credit shortfalls before the job starts. If allowed is false, Create Extraction returns a 402 error. Check your current usage on the dashboard.
Next steps. Create Extraction to start an extraction, or Extraction Workflow Guide for the full flow.