> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Twitter scraping cost estimator & credit quote
> Estimate API credits before exporting tweet searches, replies, followers, following, profiles, communities, or lists. The quote is free and starts no job.
For the complete documentation index, see llms.txt.
**Free.** This endpoint does not consume credits.
```bash cURL theme={null}
curl -X POST https://xquik.com/api/v1/extractions/estimate \
-H "x-api-key: xq_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"toolType": "reply_extractor",
"targetTweetId": "1893704267862470862",
"resultsLimit": 500
}' | jq
```
```javascript Node.js theme={null}
const response = await fetch("https://xquik.com/api/v1/extractions/estimate", {
method: "POST",
headers: {
"x-api-key": "xq_YOUR_KEY_HERE",
"Content-Type": "application/json",
},
body: JSON.stringify({
toolType: "reply_extractor",
targetTweetId: "1893704267862470862",
resultsLimit: 500,
}),
});
const data = await response.json();
if (data.allowed) {
// Safe to proceed with extraction
}
```
```python Python theme={null}
import requests
response = requests.post(
"https://xquik.com/api/v1/extractions/estimate",
headers={"x-api-key": "xq_YOUR_KEY_HERE"},
json={
"toolType": "reply_extractor",
"targetTweetId": "1893704267862470862",
"resultsLimit": 500,
},
)
data = response.json()
if data.get("allowed"):
# Safe to proceed with extraction
pass
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
body, _ := json.Marshal(map[string]interface{}{
"toolType": "reply_extractor",
"targetTweetId": "1893704267862470862",
"resultsLimit": 500,
})
req, err := http.NewRequest("POST", "https://xquik.com/api/v1/extractions/estimate", bytes.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var data map[string]interface{}
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
panic(err)
}
fmt.Println(data)
}
```
## 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
| Twitter scraping task | `toolType` | Required target | Estimated results |
| - | - | - | - |
| Search tweets with filters | `tweet_search_extractor` | `searchQuery` | Matching tweet search results |
| Export tweet replies | `reply_extractor` | `targetTweetId` | Replies beneath one tweet |
| Export followers | `follower_explorer` | `targetUsername` | Follower profiles |
| Export following | `following_explorer` | `targetUsername` | Followed profiles |
| Export profile tweets | `post_extractor` | `targetUsername` | Tweets from one profile |
| Export community tweets | `community_post_extractor` | `targetCommunityId` | Tweets from one community |
| Export list members | `list_member_extractor` | `targetListId` | Profiles inside one list |
| Export list tweets | `list_post_extractor` | `targetListId` | Tweets from list members |
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
Your API key. Session cookie authentication is also supported. Generate a key from the [dashboard](https://xquik.com/dashboard).
Must be `application/json`.
The estimator accepts the same fields as Create Extraction.
## Body
Extraction tool to run or estimate. See the endpoint's tool list.
### Single targets
Tweet ID for a tweet-centered extraction.
Username for an account-centered extraction. You may include `@`.
Community ID for a community extraction.
List ID for a list extraction.
Space ID for `space_explorer`.
Query for `tweet_search_extractor` or `community_search`.
### Collection targets
Process 1-10,000 Tweet IDs in one collection job.
Process 1-100 unique usernames in one job. `tweet_search_extractor` collects their posts.
Process 1-100 unique community IDs in one collection job.
Process 1-100 unique List IDs in one collection job.
Process 1-100 unique search queries in one collection job.
Process up to 10,000 mixed targets with automatic routing.
Each target accepts a supported string or `{ "kind": "...", "value": "..." }`.
Process up to 100 profile relations in one collection job.
Each relation target uses `{ "relation": "...", "value": "..." }`.
### Collection controls
Search ranking: `Latest`, `Top`, or `Both`. Defaults to `Latest`.
Maximum unique results to emit. Defaults to `10,000`. Use any positive integer.
Maximum results collected for each target. Minimum: `1`.
Reply pages collected per target. Range: `1-1,000`.
Resume one reply target from this cursor.
Merge duplicates across targets. Defaults to `true`.
Duplicate handling: `none`, `first`, or `merge`.
Use `dedupeMode=merge`. Defaults to `false`.
Add matched search terms to collection metadata. Defaults to `false`.
Add source target metadata to each result. Defaults to `true`.
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
Strategy: `auto`, `complete`, `direct`, `search`, or `thread`.
Reply scope: `all`, `direct`, or `nested`. Defaults to `all`.
Maximum nested reply depth. Minimum: `1`.
Order: `relevance`, `latest`, `oldest`, or `likes`.
Exclude replies from the source author. Defaults to `false`.
Include the source post. Defaults to `false`.
Return only replies with media. Defaults to `false`.
Reply start time as ISO 8601 or Unix seconds.
Reply end time as ISO 8601 or Unix seconds.
### Tweet result filters
Minimum Tweet view count.
Minimum Tweet bookmark count.
Maximum Tweet like count.
Maximum Tweet repost count.
Maximum Tweet reply count.
Maximum Tweet quote count.
Return only Blue-verified Tweet authors. Defaults to `false`.
X search no longer supports `cardName`, so a search with it finds no Tweets.
X search no longer supports `source`, so a search with it finds no Tweets.
X search no longer supports `excludeSource`, so a search ignores it.
X search no longer supports `geocode`, so a search with it finds no Tweets.
Return Tweets whose IDs exceed this ID.
Return Tweets at or below this ID.
Match a place name.
X search no longer supports `within`, so a search with it finds no Tweets. Use
`near` alone.
Match Tweets inside a recent time window.
Return only native reposts. Defaults to `false`.
Enable safe search. Defaults to `false`.
X no longer searches `filter:news`, so leave this unset.
### Profile result filters
Minimum profile follower count.
Maximum profile follower count.
Minimum profile following count.
Maximum profile following count.
Minimum profile post count.
Maximum profile post count.
Minimum profile age in days.
Match the exact profile verification type.
Require a profile website. Defaults to `false`.
Require a profile location. Defaults to `false`.
Require bio terms separated by commas or lines.
Require matching profile location text.
Require matching username text.
### Tweet search filters
These fields apply to `tweet_search_extractor`.
Match an author username without `@`.
Match replies sent to a username.
Match Tweets mentioning a username.
Match a language code, such as `en`.
Include Tweets on or after `YYYY-MM-DD`.
Include Tweets up to `YYYY-MM-DD`, a UTC day, inclusive, so its own Tweets count.
Media: `images`, `videos`, `gifs`, `media`, `links`, or `none`.
Minimum like count.
Minimum repost count.
Minimum reply count.
Minimum quote count.
Return only verified authors.
Reply mode: `include`, `exclude`, or `only`.
Repost mode: `include`, `exclude`, or `only`.
Quote mode: `include`, `exclude`, or `only`.
Match one exact phrase.
Exclude words or quoted phrases.
Match any listed word or quoted phrase.
Match hashtags separated by spaces, commas, or lines.
Match cashtags separated by spaces, commas, or lines.
Match a URL substring or domain.
Match a conversation ID.
Return only replies to this Tweet ID.
Return only quotes of this Tweet ID.
Return only reposts of this Tweet ID.
Search within a List ID.
Search within a place ID.
Search within a country code.
Set a geographic center and radius.
Set a geographic bounding box.
Append raw advanced search syntax.
## Response
### 200 OK
Whether the extraction can proceed given the current credit balance.
Data source used for the estimate. One of: `collection`, `followers`, `following`,
`paginationCap`, `quoteCount`, `replyCount`, `resultsLimit`, `retweetCount`, `unknown`.
Estimated number of results the extraction will return.
Credits this extraction will consume (stringified integer).
Credits available in your balance (stringified integer).
Resolved X user ID from count-based profile estimates.
```json theme={null}
{
"allowed": true,
"creditsRequired": "500",
"creditsAvailable": "50000",
"estimatedResults": 250,
"source": "replyCount",
"resolvedXUserId": "123456"
}
```
When `allowed` is `false`, credits required exceed the available balance:
```json theme={null}
{
"allowed": false,
"creditsRequired": "250000",
"creditsAvailable": "18000",
"estimatedResults": 250000,
"source": "followers"
}
```
### 400 Invalid input
```json theme={null}
{ "error": "invalid_input" }
```
The request body is missing or malformed. Send `toolType` and its matching target field.
### 400 Invalid tool type
```json theme={null}
{ "error": "invalid_tool_type" }
```
The `toolType` value is not one of the 23 supported tools.
### 401 Unauthenticated
```json theme={null}
{ "error": "unauthenticated" }
```
Missing or invalid API key.
### 402 Insufficient credits
```json theme={null}
{ "error": "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
```json theme={null}
{ "error": "tweet_not_found", "message": "Tweet not found" }
```
The target tweet does not exist, was deleted, or the ID is invalid.
```json theme={null}
{ "error": "user_not_found", "message": "X user not found" }
```
The target user does not exist or is suspended.
### 429 Rate limited
```json theme={null}
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Try again later.",
"retryAfter": 60
}
```
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:
```json theme={null}
{
"checkpoint_type": "extraction_estimate",
"toolType": "reply_extractor",
"targetTweetId": "1893704267862470862",
"resultsLimit": 500,
"estimatedResults": 500,
"creditsRequired": "500",
"creditsAvailable": "50000",
"allowed": true,
"source": "replyCount",
"next_action": "create_extraction",
"create_path": "/api/v1/extractions",
"fallback_action": "lower_results_limit_or_add_credits"
}
```
When `allowed` is `true`, send the same `toolType`, target fields, filters, and `resultsLimit` to [Create Extraction](/api-reference/extractions/create). Store the returned job ID from that `202 Accepted` receipt.
When `allowed` is `false`, lower `resultsLimit`, narrow the target or filters, or add credits before calling [Create Extraction](/api-reference/extractions/create).
Store `source` so operators know whether the estimate came from `replyCount`, `followers`, `resultsLimit`, `paginationCap`, or another supported count.
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](https://xquik.com/dashboard).
**Next steps.** [Create Extraction](/api-reference/extractions/create) to start an extraction, or [Extraction Workflow Guide](/guides/extraction-workflow) for the full flow.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.