# X (Twitter) API (ScrapeIO)

10 endpoints for public X (Twitter) data. Same response format and field names as every other platform.

## Basics

- Base URL: `https://scrapeio.com`
- Auth: send your key in the `x-api-key` header. Get a key at https://scrapeio.com/login (100 free credits, no card).
- Every endpoint is a GET with query parameters and returns JSON:
  `{ "success": true, "cached": false, "credits_used": 1, "credits_remaining": 99, "data": { ... } }`
- Field names are the same on every platform (`handle`, `followers`, `plays`, `likes`, `comments`, `created_at`).
- Lists return `data.items`, `data.cursor` and `data.has_more`. Pass `cursor` back to get the next page.
- Each endpoint has one listed price. Cached repeats, failed calls, private and not-found answers cost 0.
- Limit: 300 requests a minute per key.

## Errors

| Status | Meaning | Charged |
| --- | --- | --- |
| 200 | Success | Yes, unless cached |
| 400 | A parameter is missing or wrong | No |
| 401 | The key is missing or invalid | No |
| 402 | Not enough credits | No |
| 403 | The account or post is private | No |
| 404 | Not found on the platform | No |
| 429 | More than 300 requests a minute | No |
| 502 | Every source is down; retry shortly | No |

### GET /v1/twitter/profile

X profile: bio, avatar, followers, following, post count. Price: 1 credit. MCP tool: `twitter_profile`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | X username, with or without @. |

```bash
curl "https://scrapeio.com/v1/twitter/profile?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/user-tweets

A profile's posts, newest first, with views, likes, reposts, replies and bookmarks. Price: 1 credit. MCP tool: `twitter_user_tweets`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | string | yes | X username, with or without @. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/twitter/user-tweets?handle=nike" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/tweet

One post by URL or id. Price: 1 credit. MCP tool: `twitter_tweet`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | X post URL. |

```bash
curl "https://scrapeio.com/v1/twitter/tweet?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/tweet/replies

Latest replies to a post. Price: 1 credit. MCP tool: `twitter_replies`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | X post URL. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/twitter/tweet/replies?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/search

Search X posts. X search operators work. Price: 1 credit. MCP tool: `twitter_search`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Search text. |
| `type` | string (top, latest) | no | Ranking. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/twitter/search?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/trends

Trending topics for a country. Price: 1 credit. MCP tool: `twitter_trends`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | no | Two-letter country code. |

```bash
curl "https://scrapeio.com/v1/twitter/trends" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/community

An X community: name, description, topic, member count and rules. Price: 1 credit. MCP tool: `twitter_community`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Community URL. |

```bash
curl "https://scrapeio.com/v1/twitter/community?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/community/tweets

Latest posts in an X community, with views and likes. Price: 1 credit. MCP tool: `twitter_community_tweets`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Community URL. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/twitter/community/tweets?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/search/posts

X's Top results for a keyword, with views and likes. Price: 1 credit. MCP tool: `twitter_search_posts`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Search text. |
| `cursor` | string | no | Cursor from the previous page's data.cursor. |

```bash
curl "https://scrapeio.com/v1/twitter/search/posts?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/twitter/tweet/transcript

Transcript Price: 5 credits. MCP tool: `twitter_tweet_transcript`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Tweet URL |
| `cache_max_age` | string (1d, 3d, 7d, 14d, 30d) | no | If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "ca |

```bash
curl "https://scrapeio.com/v1/twitter/tweet/transcript?url=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```