Skip to main content
Choose the output shape before wiring a worker, dashboard, spreadsheet, or archive. Xquik gives you live JSON pages for endpoint calls. It also gives you saved JSON pages for extraction jobs. It adds file exports for downstream tools and draw exports for giveaway audits. This guide covers Xquik API result files. It does not download tweet images or videos. It also does not export your private X (Twitter) account archive. Read Read Data Richness before choosing columns downstream. It lists every optional tweet, profile, and media field. The export endpoint selects a file format. Filter or select columns downstream.

Choose the output shape

Live JSON page

Use endpoints such as GET /api/v1/x/tweets/search, GET /api/v1/x/users/{id}/tweets, and GET /api/v1/x/users/{id}/followers. Use them when your app needs fresh API results and endpoint-specific cursors.

Saved JSON rows

Use GET /api/v1/extractions/{id}?limit=1000&cursor={nextCursor} when a saved extraction job holds the data. The response includes job, results, hasMore, and optional nextCursor.

File export

Use GET /api/v1/extractions/{id}/export?format=csv when a downstream tool needs a downloaded file. Supported formats are csv, json, xlsx, md, md-document, pdf, and txt.

Draw export

Use GET /api/v1/draws/{id}/export?format=csv&type=winners when you need giveaway winners or entry rows. Set type to winners or entries.

Output decision map

App UI

Call the live JSON endpoint. Store the endpoint cursor with the filters that produced the page.

Worker or queue

Read saved extraction pages and append JSON Lines. Resume with cursor when hasMore is true.

CRM or spreadsheet

Download CSV for simple imports, or XLSX when analysts need a workbook.

Archive or report

Download JSON for replay and Markdown or TXT for text archives. Download PDF for a shareable report file.

Match the format to the handoff

Choose a format from the next consumer’s exact requirements. Do not convert a file twice when Xquik already returns the required format. Use a live JSON page when code needs fresh data. That means tweets, followers, following rows, replies, profiles, or media fields. Keep the documented endpoint cursor with the same request filters. Use saved extraction JSON pages when a worker needs incremental processing. Append each completed page to JSON Lines through an idempotent sink. Use the extraction ID and requested cursor value as the page key. Store the page and its nextCursor in one atomic commit. A retry must replace or skip an existing page key. It must not append duplicate tweets, followers, or replies. Use a JSON file when an application needs one structured download. The export contains the documented columns for that extraction tool. Store the extraction ID, tool type, and selected filters beside the file. Use CSV for CRM or spreadsheet imports. CSV exports include one header row. They also neutralize spreadsheet formula prefixes in result cells. Use XLSX when analysts need an Excel workbook. People may need a readable review file instead of an import file. If so, use Markdown, PDF, or TXT.

Pagination and cursor map

Direct X API pages expose endpoint-specific cursor fields such as has_next_page and next_cursor. Keep the same query filters between requests. Only change the cursor parameter documented on that endpoint. Extraction result pages use hasMore and nextCursor. Pass nextCursor back as cursor. Use limit up to 1000. The default is 100. File exports include every row in 1 download. A PDF above 10,000 rows comes as a ZIP of PDF parts. Use extraction JSON pages or JSON Lines to process larger jobs incrementally. To work through results as you go, page them through GET /api/v1/extractions/{id}. Keep cursor, hasMore, and nextCursor in one checkpoint. Never continue from the downloaded file’s last visible value. The file endpoint returns every row ordered by result ID.

Format map

CSV

Use it for spreadsheet imports and CRM uploads. The response content type is text/csv; charset=utf-8.

JSON file

Use it for replay, durable archives, and application handoffs. The file is a JSON array containing the extraction tool’s documented columns. The response content type is application/json; charset=utf-8.

XLSX

Use it for analysts who need a workbook. The response content type is application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

Markdown

Use it for docs and text review. md returns a Markdown table. md-document returns numbered sections with labeled fields. Both return text/markdown; charset=utf-8.

PDF

Use it for a shareable report snapshot. The response content type is application/pdf, or application/zip for PDF parts above 10,000 rows.

TXT

Use it for plain text archives. The response content type is text/plain; charset=utf-8.

Download and validate an export

Use the server filename from Content-Disposition. curl can apply that filename without parsing the header yourself.
Validate these properties before handing the file to another system.
  1. Require HTTP 200.
  2. Match Content-Type to the requested format.
  3. Store the Content-Disposition filename.
  4. Reject an unexpectedly empty file.
  5. Parse the selected format before marking the handoff complete.
  6. Record the parsed row count and extraction ID.
  7. Calculate a local checksum when an audit requires one.
Do not assume a filename proves the format. Verify the response header and parser result. Never print CSV, JSON, XLSX, PDF, or TXT bytes to shared logs.

Handoff checkpoint

Store enough context to resume a job and verify filters later. Also store enough to download the right format later.
Your workflow calculates local_sha256 after download. Xquik does not return that field in the export response.

Handle export failures

  • For 400 invalid_format, use one of the 7 documented format values.
  • For 401 unauthenticated, replace the missing or invalid credential.
  • For 404 not_found, verify the extraction or draw ID belongs to the account.
  • For 429 rate_limit_exceeded, wait for Retry-After before downloading again.
For draw exports, also validate type=winners or type=entries. Do not retry an unchanged 400, 401, or 404 request. Retry 429 after the documented delay.

X (Twitter) API export questions

How do I export X (Twitter) API results to CSV?

Run an extraction for tweets, followers, following rows, replies, or profiles. After completion, request its export endpoint with format=csv.

Can I export tweets as JSON?

Yes. Use live JSON pages for incremental processing. Use format=json for one saved extraction file with every row.

Should I use CSV or JSON for Twitter results?

Use CSV for CRM and spreadsheet imports. Use JSON for applications, replay, and structured result fields. Choose before building the downstream parser.

When should I use XLSX instead of CSV?

Use XLSX when analysts need an Excel workbook. Use CSV when another system expects a simple delimited import.

Can I export more than 100,000 rows?

Yes. File exports include every row. To resume a large job, process saved JSON pages and append JSON Lines. Then continue from cursor.

Why does a large PDF come as a ZIP?

Each PDF file holds up to 10,000 rows. A larger export comes as 1 ZIP of PDF parts. You still get every row. Choose CSV, JSON, XLSX, Markdown, or TXT for 1 file.

What is the difference between md and md-document?

md returns a Markdown table. md-document returns numbered result sections with labeled fields. Both use the Markdown response content type.

Does this download X (Twitter) images or videos?

No. This guide exports documented result fields. Use returned media URLs when your workflow separately processes tweet images or videos.

Does this export my private X (Twitter) account archive?

No. These endpoints export Xquik extraction or draw results. Use X’s account archive process for your private account archive.

Safety checklist

Do not print downloaded export bytes to shared logs.
Store the Content-Disposition filename if your workflow needs stable file names.
Validate format before making the request. Invalid formats return a 400 error. Store the job ID, tool type, filters, and cursor with the downstream task. Also store the chosen export path with it.

Next steps

Extraction workflow

Build saved extraction jobs, poll results, and export finished rows.

Export extraction

Download saved extraction rows as CSV, JSON, XLSX, Markdown, PDF, or TXT.

Export draw

Download giveaway winners or entries.

Follower export CRM

Move follower data into CSV and CRM workflows.