# xscraper

> X (Twitter) data API for developers and AI agents: profiles, tweets, search, followers, lists and trends over REST, with a fixed token price per call.

Send your API key in the `x-api-key` header. Every endpoint is a GET that returns JSON in one envelope (`success`, `message`, `data`, `errors`). Each call costs its endpoint's token price; every response reports `x-tokens-cost` and `x-tokens-remaining`. Failed calls are refunded, a 404 is charged. New accounts get 1,000 free tokens after confirming their email.

## Docs

- [API documentation](https://xscraper.online/docs): quickstart, tokens and pricing, responses, rate limits
- [Authentication](https://xscraper.online/docs#authentication): the API key header and key rules
- [Errors](https://xscraper.online/docs#errors): status codes and which ones are charged

## Endpoints

- [Profile by username](https://xscraper.online/docs/profile_by_username): Full public profile: bio, counts, avatar, banner, verification. GET /api/v1/twitter/users/profile_by_username/:username, 1 token
- [Profile by user ID](https://xscraper.online/docs/profile_by_userid): Profile for a numeric user ID. Resolves the username first, up to 4 upstream calls. GET /api/v1/twitter/users/profile_by_userid/:userId, 3 tokens
- [Username to user ID](https://xscraper.online/docs/user_id): Resolve a screen name to its numeric user ID. GET /api/v1/twitter/users/user_id/:username, 1 token
- [Search profiles](https://xscraper.online/docs/search_profiles): Find accounts matching a query, with cursor pagination. GET /api/v1/twitter/users/search_profiles, 4–6 tokens
- [User tweets](https://xscraper.online/docs/user_tweets): Most recent tweets from a user, newest first. GET /api/v1/twitter/users/tweets/:username, 3–7 tokens
- [Latest tweet](https://xscraper.online/docs/latest_tweet): The single most recent tweet from a user. GET /api/v1/twitter/users/latest_tweet/:username, 1 token
- [User tweets and replies](https://xscraper.online/docs/user_replies): Tweets and replies from a user, newest first. GET /api/v1/twitter/users/replies/:username, 3–7 tokens
- [User tweets by ID](https://xscraper.online/docs/tweets_by_user_id): Most recent tweets for a numeric user ID. GET /api/v1/twitter/users/tweets_by_user_id/:userId, 3–7 tokens
- [User tweets and replies by ID](https://xscraper.online/docs/replies_by_user_id): Tweets and replies for a numeric user ID. GET /api/v1/twitter/users/replies_by_user_id/:userId, 3–7 tokens
- [Liked tweets](https://xscraper.online/docs/user_likes): Tweets a user liked, with cursor pagination. GET /api/v1/twitter/users/likes/:username, 4–8 tokens
- [Tweet by ID](https://xscraper.online/docs/tweet): A single tweet with media, counts and author. GET /api/v1/twitter/tweets/:tweetId, 1 token
- [Tweet replies](https://xscraper.online/docs/tweet_replies): Replies in a tweet's conversation, 20 per page. GET /api/v1/twitter/tweets/:tweetId/replies, 4 tokens
- [Tweet quotes](https://xscraper.online/docs/tweet_quotes): Quote tweets of a tweet, 20 per page. GET /api/v1/twitter/tweets/:tweetId/quotes, 4 tokens
- [Search tweets](https://xscraper.online/docs/search): Search tweets with X search operators. Returns up to `count` results. GET /api/v1/twitter/tweets/search, 6–14 tokens
- [Advanced search](https://xscraper.online/docs/advanced_search): Search tweets page by page. Pass `next` back as `cursor` for the next page. GET /api/v1/twitter/tweets/advanced_search, 8–12 tokens
- [Followers](https://xscraper.online/docs/followers): Accounts following a user, up to 50 per page. Pass `next` back as `cursor` for more. GET /api/v1/twitter/users/followers/:userId, 4 tokens
- [Following](https://xscraper.online/docs/following): Accounts a user follows, up to 50 per page. Pass `next` back as `cursor` for more. GET /api/v1/twitter/users/following/:userId, 4 tokens
- [List tweets](https://xscraper.online/docs/list_tweets): Tweets from a list timeline, with cursor pagination. GET /api/v1/twitter/lists/:listId/tweets, 3–7 tokens
- [Trends](https://xscraper.online/docs/trends): Current trending topics. GET /api/v1/twitter/trends, 2 tokens

## Machine-readable

- [OpenAPI 3.1 spec](https://xscraper.online/openapi.json): every endpoint with parameters, prices and example responses