API documentation

A REST API for public X data: profiles, tweets, search, followers, lists and trends. Every endpoint is a GET, returns JSON, and costs a fixed number of tokens shown below. New accounts get 1,000 tokens once their email is confirmed.

Quickstart

Create an account and confirm your email.
Create your API key on the API key page. It is shown once, so store it somewhere safe.
Send it in the x-api-key header:

Request

curl "https://api.xscraper.online/api/v1/twitter/users/profile_by_username/jack" \
  -H "x-api-key: $XSCRAPER_KEY"

Authentication

Every request needs x-api-key: <your key>. Keys start with xs_. Each account has one key; rotating it issues a new one and stops the old one at once. Keep the key on your server. Do not ship it in browser or mobile code.

Tokens and pricing

Each call costs its endpoint's price. Endpoints that take count charge a base price plus a price per page of results, so asking for more costs more. The price is charged only when the call succeeds: any error response is refunded, except 404 (not found), which is a real answer and is charged. Every response reports x-tokens-cost and x-tokens-remaining.

Endpoint	Path	Min	Max
Tweets
User tweets/users/tweets/:username	/users/tweets/:username	3	7
Latest tweet/users/latest_tweet/:username	/users/latest_tweet/:username	1	1
User tweets and replies/users/replies/:username	/users/replies/:username	3	7
User tweets by ID/users/tweets_by_user_id/:userId	/users/tweets_by_user_id/:userId	3	7
User tweets and replies by ID/users/replies_by_user_id/:userId	/users/replies_by_user_id/:userId	3	7
Liked tweets/users/likes/:username	/users/likes/:username	4	8
Tweet by ID/tweets/:tweetId	/tweets/:tweetId	1	1
Tweet replies/tweets/:tweetId/replies	/tweets/:tweetId/replies	4	4
Tweet quotes/tweets/:tweetId/quotes	/tweets/:tweetId/quotes	4	4
Search
Search profiles/users/search_profiles	/users/search_profiles	4	6
Search tweets/tweets/search	/tweets/search	6	14
Advanced search/tweets/advanced_search	/tweets/advanced_search	8	12
Profiles
Profile by username/users/profile_by_username/:username	/users/profile_by_username/:username	1	1
Profile by user ID/users/profile_by_userid/:userId	/users/profile_by_userid/:userId	3	3
Username to user ID/users/user_id/:username	/users/user_id/:username	1	1
Social graph
Followers/users/followers/:userId	/users/followers/:userId	4	4
Following/users/following/:userId	/users/following/:userId	4	4
Lists
List tweets/lists/:listId/tweets	/lists/:listId/tweets	3	7
Trends
Trends/trends	/trends	2	2

Responses

Every response, success or error, uses the same envelope. The payload is in data.

Success

{
  "success": true,
  "message": "Profile for @jack",
  "data": {
    "userId": "12",
    "username": "jack"
  },
  "errors": null
}

Error (402)

{
  "success": false,
  "message": "Not enough tokens: this call costs 14 and your balance is 10.",
  "data": null,
  "errors": [
    {
      "field": "balance",
      "message": "insufficient_tokens"
    }
  ]
}

Errors

Status	Meaning
400	A parameter is missing or invalid. The message says which.
401	Missing, unknown or revoked x-api-key.
402	Your balance is lower than the call's price. Nothing was charged.
403	The endpoint needs an admin key.
404	The user, tweet or list does not exist or is not visible. Charged: the lookup ran.
429	More than 100 requests in a minute on one key. Wait for Retry-After seconds.
503	The scraper pool is busy. Retry after the Retry-After header.
5xx	Upstream failure. Safe to retry.

Rate limits

Each key can make 100 requests per minute. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 also carries Retry-After. Rate limited calls are not charged.

All endpoints

The same list is available as an OpenAPI 3.1 spec at /openapi.json and as a plain-text summary for AI agents at /llms.txt.