> ## 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 extraction status & result progress
> Inspect an extraction job's status, tool, progress, row count, and paginated tweet, follower, reply, profile, timeline, or list results. Polling is free.
For the complete documentation index, see llms.txt.
**Free.** This endpoint does not consume credits.
```bash cURL theme={null}
curl -X GET "https://xquik.com/api/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890?limit=100" \
-H "x-api-key: xq_YOUR_KEY_HERE" | jq
```
```javascript Node.js theme={null}
const extractionId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const params = new URLSearchParams({ limit: "100" });
const response = await fetch(`https://xquik.com/api/v1/extractions/${extractionId}?${params}`, {
method: "GET",
headers: {
"x-api-key": "xq_YOUR_KEY_HERE",
},
});
const data = await response.json();
```
```python Python theme={null}
import requests
extraction_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
f"https://xquik.com/api/v1/extractions/{extraction_id}",
headers={"x-api-key": "xq_YOUR_KEY_HERE"},
params={"limit": 100},
)
data = response.json()
```
```go Go theme={null}
package main
import (
"encoding/json"
"fmt"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://xquik.com/api/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890?limit=100", nil)
if err != nil {
panic(err)
}
req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
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)
}
```
## Headers
Your API key. Session cookie authentication is also supported. Generate a key from the [dashboard](https://xquik.com/dashboard).
## Path parameters
Extraction job ID returned from [Create Extraction](/api-reference/extractions/create) or [List Extractions](/api-reference/extractions/twitter-scraping-job-history).
## Query parameters
Number of results to return per page. Default and maximum: `1000`.
Pass the previous `nextCursor` unchanged. Do not send `offset`. It returns `400`.
Wait up to 10 seconds when the job is active. Defaults to `0`.
Use `compact` for core fields and tweet counts. Use `full` for nested enrichment. Use `raw` for a source copy. Defaults to `full`.
Keep enrichment `nested` or merge it with `flat`.
Field names: `source`, `camelCase`, or `snake_case`.
Deprecated. Use `outputMode=raw`.
| Extraction result page column | Response source | Export rule |
| - | - | - |
| Job ID | `job.id` | Keep this ID with every exported row. |
| Extraction tool | `job.toolType` | Record which tool produced the rows. |
| Job state | `job.status` | Export final rows only after completion. |
| Total rows | `job.totalResults` | Compare this count with all saved pages. |
| Result ID | `results[].id` | Use this ID for result-page deduplication. |
| X user ID | `results[].xUserId` | Join profile records on this ID. It does not change. |
| Tweet fields | `tweetId`, `tweetText`, and `tweetCreatedAt` | Store them only when returned. |
| More pages | `hasMore` | Continue only while this value is `true`. |
| Next page | `nextCursor` | Pass this value as the next `cursor` parameter. |
## Response
### 200 OK
Extraction job metadata.
**Job object fields.**
Unique extraction job ID.
Tool type used for this extraction.
Job status: `completed`, `failed`, or `running`.
Total number of extracted results.
Target tweet ID. Present for tweet-based tools.
Target username. Present for user-based tools.
Target X user ID. Present for user-based tools.
Target community ID. Present for `community_extractor`, `community_moderator_explorer`,
`community_post_extractor`, `community_search`.
Search query. Present for `people_search`, `community_search`.
Error description. Only present for failed jobs. `errorXAccountRequired` means the tool needs your
connected X account.
ISO 8601 timestamp of when the job was created.
ISO 8601 timestamp of when the job finished. Only present for completed jobs.
Array of extracted user/tweet records for the current page.
Every result includes `id` and `xUserId`. The API omits all other fields when unavailable and never sets them to `null`. Check that a field is present before accessing it.
**Result object fields.**
Unique result ID.
X user ID.
X username (handle). Omitted if unavailable.
X display name. Omitted if unavailable.
Follower count at time of extraction. Omitted if unavailable.
Whether the user has a verified badge. Omitted if unavailable.
URL to the user's profile image. Omitted if unavailable.
Tweet ID. Omitted for non-tweet-based extractions.
Canonical X post URL. Omitted for non-tweet-based extractions.
Tweet text content. Omitted for non-tweet-based extractions.
ISO 8601 timestamp of the tweet. Omitted for non-tweet-based extractions.
Attached media with `outputPreset=flat`. Full nested output stores it at
`enrichmentData.tweet.media`.
Likes. Omitted when unavailable.
Reposts. Omitted when unavailable.
Replies. Omitted when unavailable.
Quotes. Omitted when unavailable.
Views. Omitted when unavailable.
Bookmarks. Omitted when unavailable.
ISO 8601 timestamp of when the result was created.
Additional profile, Tweet, media, and article metadata. Compact output omits this object. Full
output keeps it nested. Flat output merges its fields into the result.
Full profile, as `GET /x/users/{id}` returns it. Present when the job sets `enrichProfiles` for
`follower_explorer`, `following_explorer`, `verified_follower_explorer`, `people_search` or
`repost_extractor`. Omitted when the profile read fails. Flat output keeps it as a nested
`profile` object.
Whether more results exist beyond this page.
Recommended delay before another immediate check.
Relative polling URL. It waits 10 seconds and returns 1 compact row.
Cursor for the next `cursor` parameter. Only present when `hasMore` is `true`.
With `outputMode=compact`, tweet results keep `tweetUrl`, `likeCount`,
`retweetCount`, `replyCount`, `quoteCount`, `viewCount`, and `bookmarkCount`.
Compact output omits `xProfileImageUrl` and `enrichmentData`.
### 401 Unauthenticated
```json theme={null}
{ "error": "unauthenticated" }
```
Missing or invalid API key.
### 404 Not found
```json theme={null}
{ "error": "not_found" }
```
No extraction job exists with this ID, or it belongs to a different account.
### 429 Rate limited
```json theme={null}
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Try again later.",
"retryAfter": 1
}
```
Wait for the `Retry-After` value before polling again.
## Paginating results
The API orders results by ID ascending. To iterate through all results for a large extraction:
1. Make the initial request without the `cursor` parameter.
2. Check `hasMore`. Pass `nextCursor` as the next `cursor` value.
3. Repeat until `hasMore` is `false`.
```javascript theme={null}
import { appendFile } from "node:fs/promises";
const extractionId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
let cursor = undefined;
let pageIndex = 0;
do {
const params = new URLSearchParams({ limit: "1000" });
if (cursor) params.set("cursor", cursor);
const pageCursor = cursor ?? null;
const response = await fetch(`https://xquik.com/api/v1/extractions/${extractionId}?${params}`, {
headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
});
const data = await response.json();
const rows = data.results.map((result) => ({
extraction_id: extractionId,
row_id: result.id,
x_user_id: result.xUserId,
x_username: result.xUsername,
tweet_id: result.tweetId,
tweet_text: result.tweetText,
page_index: pageIndex,
page_cursor: pageCursor,
next_cursor: data.nextCursor ?? null,
has_more: data.hasMore,
handoff_format: "jsonl",
}));
if (rows.length > 0) {
await appendFile(
"xquik-extraction-results.jsonl",
`${rows.map((row) => JSON.stringify(row)).join("\n")}\n`,
);
}
cursor = data.hasMore ? data.nextCursor : undefined;
pageIndex += 1;
} while (cursor);
```
## Cursor handoff
Use `GET /extractions/{id}` when an integration needs structured JSON rows,
incremental checkpoints, or more rows than a file export can return. Treat
`nextCursor` as an opaque checkpoint and pass it back as `cursor`.
Store `extraction_id`, `page_index`, `page_cursor`, `next_cursor`,
`has_more`, and `result_count` after each successful page.
Store selected fields such as `row_id`, `x_user_id`, `x_username`,
`tweet_id`, and `tweet_text`. Do not write raw result arrays to shared logs.
Stream pages to `xquik-extraction-results.jsonl` when you need replayable
rows or results beyond the export row cap.
Use [Export Extraction](/api-reference/extractions/export) when CSV, JSON,
XLSX, Markdown, PDF, or TXT files are enough.
Store page checkpoints separately from row data:
```json theme={null}
{
"extraction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"page_index": 3,
"page_cursor": "990100",
"next_cursor": "990200",
"has_more": true,
"result_count": 1000,
"handoff_format": "jsonl"
}
```
**Next steps.** [Export Extraction](/api-reference/extractions/export) to download all results as CSV, XLSX, or Markdown, or [List Extractions](/api-reference/extractions/twitter-scraping-job-history) to browse your job history.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.