Queued jobs

When to use a job

Use a job when you want many pages and can wait. Two operations:

Other collections, such as followers, use live routes with cursor pagination.

Create a job

POST /v1/jobs with a JSON body. limit is the number of records (default 100, capped by the service). level defaults to moderate.

curl "https://twitterxapi.com/api/v1/jobs" -X POST \
  -H "Authorization: Bearer $TWITTERXAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"user_tweets","username":"marclou","limit":500}'

The response is 202 Accepted with the job record:

{
  "id": "6f1c2d0e-…",
  "operation": "user_tweets",
  "status": "queued",
  "level": "moderate",
  "username": "marclou",
  "requestedLimit": 500,
  "deliveredCount": 0,
  "reservedMicros": 50000,
  "costMicros": 0,
  "createdAt": "2026-10-02T09:15:00.000Z"
}

Amounts ending in Micros are millionths of a US dollar: 50000 is $0.05.

Check status

GET /v1/jobs/{jobId}. Poll every few seconds. status moves from queued to running, then ends as succeeded, failed or cancelled. A failed job includes errorCode.

curl "https://twitterxapi.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"

Download the result

A succeeded job has resultUrl, a private link to gzipped NDJSON, one record per line. The link expires; poll the job for a fresh one. The dashboard lists recent jobs too.

curl -o result.jsonl.gz "$RESULT_URL"
gunzip result.jsonl.gz
head -n 2 result.jsonl

Cancel

DELETE /v1/jobs/{jobId} cancels a job that has not finished. The reserved credit is returned.

curl -X DELETE "https://twitterxapi.com/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"

Billing

• Creating a job needs at least $1 of available balance (402 queued_balance_too_low otherwise).
• The cost of the requested limit is reserved when the job is accepted.
• You pay for delivered records. The rest is refunded, and failed or cancelled jobs are refunded in full.
• Pending jobs per account are limited; extra requests return 429.