tx twitterxapi docs
Live read-only API

Public X data,
without the plumbing.

Use a small synchronous request for immediate results, or queue a larger search or timeline and download private gzip NDJSON when it finishes.

Read onlyNo X write operations.
Typed JSONNormalized users and tweets.
Explicit workRetries and account rotation stay visible.

GET STARTED

Authentication

Pass your key as a bearer token from server-side code. One active key is issued per account; replacing it immediately revokes the previous key.

export TWITTERXAPI_KEY="tx_live_…"

curl "/api/v1/users/marclou" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"

LIVE API

Endpoints

Successful collections use { items, count }. A single profile or tweet is returned directly as its normalized object.

GET

Profile by username

/v1/users/{username}

Returns one normalized public X account.

curl "/api/v1/users/marclou" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"
GET

User timeline

/v1/users/{username}/tweets?limit=20

Returns up to limit normalized tweets from an account. Live requests are capped by the service configuration.

curl "/api/v1/users/marclou/tweets?limit=20" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"
GET

Tweet details

/v1/tweets/{tweetId}

Returns a normalized tweet, author, metrics, media, and referenced tweets when available.

curl "/api/v1/tweets/1897412345678901234" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"
POST

Queue a larger result

/v1/jobs

Queues search or user_tweets work. On completion, the status response contains a short-lived private download URL for gzip-compressed NDJSON.

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

Check or cancel a job

/v1/jobs/{jobId}

Poll with GET. Cancel queued or running work with DELETE using the same URL.

curl "/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"

REFERENCE

Errors, charging, and cancellation

Errors have a stable code, message, and request ID. Live reads reserve the maximum cost, then settle against delivered items; failures are refunded. The first five requests are free. Queued reads cost less per delivered item, can be cancelled, and are refunded on terminal failure.

{
  "detail": "user not found",
  "error": {
    "code": "user_not_found",
    "message": "user not found",
    "requestId": "…"
  }
}

Queued output is newline-delimited JSON compressed with gzip. Save the result before its signed URL or configured object-retention window expires.