Lists | TwitterXAPI docs

Lists

# TwitterXAPI API reference

REST API for X data: profiles, timelines, followers, posts, threads, search, Lists, trends and communities. JSON over HTTPS.

## Authentication

- Base URL: `https://twitterxapi.com/api`. REST routes are under `/v1`. The MCP server is `https://twitterxapi.com/api/mcp`.
- Send `Authorization: Bearer $TWITTERXAPI_KEY` on every request. Read the key from the `TWITTERXAPI_KEY` environment variable; never hard-code it or print it.
- Get a key at https://twitterxapi.com/dashboard/ (sign in with Google).

## First request

```sh
curl "https://twitterxapi.com/api/v1/users/marclou" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"
```

## Conventions

- Response levels: `?level=moderate` (default, stable camelCase fields), `contentful` (compact text-first records, no numeric IDs, has `url`), `raw` (X's GraphQL response unchanged, no `pagination` object). All levels cost the same.
- Collections return one page: `{ "items": [...], "count": n, "pagination": { "next_cursor": "...", "has_more": true } }`. Pass `next_cursor` back unchanged as `cursor` (URL-encoded) until `has_more` is false or the cursor is empty. There is no page-size parameter; sending `limit` to a live route returns `400 limit_removed`.
- Keep X IDs as strings. Deduplicate by ID when paging live data.
- Errors: JSON `{ "error": { "code", "message", "requestId" } }`. Branch on `error.code`. 400 fix the request, 401 bad key, 402 add credit, 404 not found or not public, 429 and 5xx retry with backoff (honour `Retry-After`).
- Billing: prepaid credit. Collections are charged per record returned, single lookups $0.001 each. Failed requests are refunded.

## Endpoints

### Users

| Method | Path | Endpoint | Returns | Price |
| --- | --- | --- | --- | --- |
| GET | `/v1/users/{username}` | Profile by username | Account | $0.001 per request |
| GET | `/v1/users/by-id/{userId}` | Profile by ID | Account | $0.001 per request |
| GET | `/v1/users/{username}/about` | Account information | Account information | $0.001 per request |
| GET | `/v1/users/{username}/tweets` | Posts | Page of posts | $0.10 per 1,000 records |
| GET | `/v1/users/{username}/posts-and-replies` | Posts and replies | Page of posts | $0.10 per 1,000 records |
| GET | `/v1/users/{username}/media` | Media | Page of posts | $0.10 per 1,000 records |
| GET | `/v1/users/by-id/{userId}/followers` | Followers | Page of accounts | $0.01 per 1,000 accounts |
| GET | `/v1/users/by-id/{userId}/verified-followers` | Verified followers | Page of accounts | $0.05 per 1,000 accounts |
| GET | `/v1/users/by-id/{userId}/following` | Following | Page of accounts | $0.01 per 1,000 accounts |
| GET | `/v1/users/by-id/{userId}/subscriptions` | Creator subscriptions | Page of accounts | $0.01 per 1,000 accounts |

Parameters: `username` (path, required) Username without @. Letters, numbers and underscores, up to 30 characters. `level` (query) Response level. Defaults to moderate. `userId` (path, required) Numeric X user ID. Get it from the id field of a profile. `cursor` (query) Value of pagination.next_cursor from the previous page. Omit for the first page.

### Posts

| Method | Path | Endpoint | Returns | Price |
| --- | --- | --- | --- | --- |
| GET | `/v1/posts/{postId}` | Post details | Post | $0.001 per request |
| GET | `/v1/posts/{postId}/replies` | Direct replies | Page of posts | $0.10 per 1,000 records |
| GET | `/v1/posts/{postId}/thread` | Conversation thread | Page of posts | $0.10 per 1,000 records |
| GET | `/v1/posts/{postId}/retweeters` | Retweeters | Page of accounts | $0.10 per 1,000 records |

Parameters: `postId` (path, required) Numeric post ID, the number after /status/ in a post URL. `level` (query) Response level. Defaults to moderate. `cursor` (query) Value of pagination.next_cursor from the previous page. Omit for the first page.

### Search

| Method | Path | Endpoint | Returns | Price |
| --- | --- | --- | --- | --- |
| GET | `/v1/search` | Search posts | Page of posts | $0.20 per 1,000 results |
| GET | `/v1/search/users` | Search accounts | Page of accounts | $0.20 per 1,000 results |
| GET | `/v1/search/trend` | Search a trend | Page of posts | $0.20 per 1,000 results |

Parameters: `q` (query, required) X search query, 1–500 characters. URL-encode the whole value. `cursor` (query) Value of pagination.next_cursor from the previous page. Omit for the first page. `level` (query) Response level. Defaults to moderate.

### Lists

| Method | Path | Endpoint | Returns | Price |
| --- | --- | --- | --- | --- |
| GET | `/v1/lists/{listId}/posts` | List posts | Page of posts | $0.10 per 1,000 records |
| GET | `/v1/lists/{listId}/members` | List members | Page of accounts | $0.01 per 1,000 accounts |

Parameters: `listId` (path, required) Numeric ID from a List URL such as x.com/i/lists/123456789. `cursor` (query) Value of pagination.next_cursor from the previous page. Omit for the first page. `level` (query) Response level. Defaults to moderate.

### Trends

| Method | Path | Endpoint | Returns | Price |
| --- | --- | --- | --- | --- |
| GET | `/v1/trends/{category}` | Trends | Page of trends | $0.10 per 1,000 records |

Parameters: `category` (path, required) trending, news, sport, entertainment, or an X timeline ID. `cursor` (query) Value of pagination.next_cursor from the previous page. Omit for the first page. `level` (query) Response level. Defaults to moderate.

### Communities

| Method | Path | Endpoint | Returns | Price |
| --- | --- | --- | --- | --- |
| GET | `/v1/communities/{communityId}` | Community information | Community | $0.001 per request |
| GET | `/v1/communities/{communityId}/posts` | Community posts | Page of posts | $0.10 per 1,000 records |
| GET | `/v1/communities/{communityId}/members` | Community members | Page of accounts | $0.01 per 1,000 accounts |
| GET | `/v1/communities/{communityId}/moderators` | Community moderators | Page of accounts | $0.01 per 1,000 accounts |

Parameters: `communityId` (path, required) Numeric ID from a community URL such as x.com/i/communities/1493446837214187523. `level` (query) Response level. Defaults to moderate. `cursor` (query) Value of pagination.next_cursor from the previous page. Omit for the first page.

POST `/v1/search` accepts `{"query","cursor","level"}` as a JSON body for long queries.

## Queued jobs

For many pages of one account's posts or one search, queue a job and download one gzipped NDJSON file.

- `POST /v1/jobs` with JSON `{"operation":"user_tweets","username":"marclou","limit":500}` or `{"operation":"search","query":"from:marclou since:2026-01-01","limit":500}`. Optional `level`. Returns `202` with the job record.
- `GET /v1/jobs/{jobId}` to poll. `status`: queued, running, succeeded, failed, cancelled. A succeeded job has `resultUrl` (expires; poll again for a fresh link).
- `DELETE /v1/jobs/{jobId}` cancels and returns the reserved credit.
- Needs at least $1 of available balance (`402 queued_balance_too_low`). You pay for delivered records only.

## MCP

Endpoint `https://twitterxapi.com/api/mcp`, same key. Tools: `search_x`, `get_x_user`, `get_x_user_timeline`, `get_x_user_network`, `get_x_post`, `get_x_list`, `get_x_trends`, `get_x_community`. Full setup: https://twitterxapi.com/mcp-server/

Docs: https://twitterxapi.com/docs/

Endpoints

Endpoint	Returns and price
GET `/v1/lists/{listId}/posts` List posts	Page of posts · $0.10 per 1,000 records
GET `/v1/lists/{listId}/members` List members	Page of accounts · $0.01 per 1,000 accounts

All routes take Authorization: Bearer $TWITTERXAPI_KEY and level. Collections return one page; continue with the cursor.

Find the List ID

Use the number in the List URL, for example x.com/i/lists/123456789.

Read every page

GET/v1/lists/{listId}/postsPage of posts

List posts

One page from the List timeline.

Parameter	In	Description
`listId` required numeric string	path	Numeric ID from a List URL such as x.com/i/lists/123456789.
`cursor` string	query	Value of pagination.next_cursor from the previous page. Omit for the first page.
`level` raw \| moderate \| contentful	query	Response level. Defaults to moderate.

Returns: Page of posts · Price: $0.10 per 1,000 records

cURL

curl "https://twitterxapi.com/api/v1/lists/123456789/posts" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"

GET/v1/lists/{listId}/membersPage of accounts

List members

One page of accounts in the List.

Parameter	In	Description
`listId` required numeric string	path	Numeric ID from a List URL such as x.com/i/lists/123456789.
`cursor` string	query	Value of pagination.next_cursor from the previous page. Omit for the first page.
`level` raw \| moderate \| contentful	query	Response level. Defaults to moderate.

Returns: Page of accounts · Price: $0.01 per 1,000 accounts

cURL

curl "https://twitterxapi.com/api/v1/lists/123456789/members" \
  -H "Authorization: Bearer $TWITTERXAPI_KEY"