# Twitter / X Data API — profiles, tweets, replies, media, likes, tweet detail + replies, search (top/latest/people/media), followers/following, list timelines. Account-pool backed: no official API key, no quota.

> User profile by @username — name, bio, followers, following, tweet/like counts, verified, created date, location, website, avatar/banner.
> ReefAPI engine `twitter` · 14 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/twitter/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/twitter/v1/profile — 1 credit
User profile by @username — name, bio, followers, following, tweet/like counts, verified, created date, location, website, avatar/banner.

**Parameters:**
- `username` (string, required) — The @handle (with or without @).

**Returns:** user{user_id, name, username, description, followers, following, tweets, likes, media_count, verified, created_at, location, website, profile_image, profile_banner, pinned_tweet_ids, url}

**Example request body:**
```json
{
  "username": "nasa"
}
```

### POST https://api.reefapi.com/twitter/v1/user_by_id — 1 credit
User profile by numeric user_id (same fields as profile).

**Parameters:**
- `user_id` (string, required) — Numeric user id.

**Returns:** user{...} (same shape as profile)

**Example request body:**
```json
{
  "user_id": "11348282"
}
```

### POST https://api.reefapi.com/twitter/v1/user_tweets — 1 credit
A user's tweets — full text, engagement (likes/retweets/replies/quotes/views), media, quoted/retweeted, with cursor pagination.

**Parameters:**
- `username` (string, optional) — @handle (resolved to id) — or pass user_id.
- `user_id` (string, optional) — Numeric user id (skips the handle lookup).
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[]{tweet_id,text,created_at,likes,retweets,replies,quotes,views,media[],hashtags,mentions,urls,quoted,retweeted,author,url} + next_cursor + user_id

**Example request body:**
```json
{
  "username": "nasa",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/user_replies — 1 credit
A user's tweets AND replies (timeline incl. replies). Each reply also carries reply_to_text (the parent tweet's text, ≤280 chars) + reply_to_author so a reply is interpretable without a second call — resolved from the conversation already in the response.

**Parameters:**
- `username` (string, optional) — @handle — or pass user_id.
- `user_id` (string, optional) — Numeric user id.
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[]{tweet_id,text,reply_to_tweet_id,reply_to_user,reply_to_text,reply_to_author,quoted,media[],author,url,…} + next_cursor + user_id

**Example request body:**
```json
{
  "username": "nasa",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/user_media — 1 credit
A user's media tweets — photos & videos (with video_url + duration), engagement, pagination.

**Parameters:**
- `username` (string, optional) — @handle — or pass user_id.
- `user_id` (string, optional) — Numeric user id.
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[]{...,media[]{type,url,video_url,duration_ms,alt}} + next_cursor

**Example request body:**
```json
{
  "username": "nasa",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/user_likes — 1 credit
Tweets a user has liked (if the account exposes likes).

**Parameters:**
- `username` (string, optional) — @handle — or pass user_id.
- `user_id` (string, optional) — Numeric user id.
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[]{...} + next_cursor

**Example request body:**
```json
{
  "username": "nasa"
}
```

### POST https://api.reefapi.com/twitter/v1/tweet — 1 credit
A single tweet by id — full text, engagement, media, quoted/retweeted, author.

**Parameters:**
- `tweet_id` (string, required) — The tweet (status) id.

**Returns:** tweet{tweet_id,text,created_at,likes,retweets,replies,quotes,views,media[],quoted,retweeted,author,url}

**Example request body:**
```json
{
  "tweet_id": "20"
}
```

### POST https://api.reefapi.com/twitter/v1/tweet_replies — 1 credit
A tweet PLUS its replies/comments (threaded conversation) with DEEP cursor pagination.

**Parameters:**
- `tweet_id` (string, required) — The tweet id to load replies for.
- `limit` (integer, optional, default 40) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[]{...} (focal tweet first, then replies) + next_cursor

**Example request body:**
```json
{
  "tweet_id": "20",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/search — 1 credit
Search tweets or people. product=Top|Latest|People|Media. Supports X search operators in the query. Cursor pagination.

**Parameters:**
- `query` (string, required) — Search text (supports operators like from:, since:, filter:media).
- `product` (enum, optional, default "Top") — Result type. [one of: Top, Latest, People, Media]
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[] (or users[] when product=People) + next_cursor + product

**Example request body:**
```json
{
  "query": "openai",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/followers — 1 credit
A user's followers (each a full user object), paginated.

**Parameters:**
- `username` (string, optional) — @handle — or pass user_id.
- `user_id` (string, optional) — Numeric user id.
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** users[]{user_id,name,username,description,followers,...} + next_cursor

**Example request body:**
```json
{
  "username": "nasa",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/following — 1 credit
Accounts a user follows (each a full user object), paginated.

**Parameters:**
- `username` (string, optional) — @handle — or pass user_id.
- `user_id` (string, optional) — Numeric user id.
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** users[]{...} + next_cursor

**Example request body:**
```json
{
  "username": "nasa",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/list_tweets — 1 credit
Latest tweets from a Twitter List by id, paginated.

**Parameters:**
- `list_id` (string, required) — The List id — the digits in x.com/i/lists/<id>. A list id that no longer exists returns NOT_FOUND (X answers such ids with an empty timeline object, not an error).
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[]{...} + next_cursor

**Example request body:**
```json
{
  "list_id": "1011591069782499328",
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/trends — 1 credit
Current trending topics on X / Twitter (the Explore feed) — each with its name, location/category context, post-volume, and a search URL.

**Parameters:**
- `limit` (integer, optional, default 40) — Max items to return.

**Returns:** trends[]{name, category, description, url}

**Example request body:**
```json
{
  "limit": 10
}
```

### POST https://api.reefapi.com/twitter/v1/community_search — 1 credit
Search posts across X Communities by keyword — returns matching community tweets (same rich tweet shape as search).

**Parameters:**
- `query` (string, required) — Keywords to search within X Communities.
- `product` (string, optional) — Latest (chronological) or Top (relevance). [one of: Top, Latest]
- `limit` (integer, optional, default 20) — Max items to return.
- `cursor` (string, optional) — Pagination cursor from a previous response's next_cursor.

**Returns:** tweets[]{...} + next_cursor

**Example request body:**
```json
{
  "query": "artificial intelligence",
  "limit": 10
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=twitter
- Human docs page: https://reefapi.com/docs/twitter
- Overview page: https://reefapi.com/twitter-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt