# twitterapi.io — Twitter/X Data API for AI Agents (Complete Reference)

> twitterapi.io provides programmatic, pay-per-call access to Twitter/X data via a REST API and an MCP (Model Context Protocol) server. AI agents (Claude.ai, Claude Code, Cursor, Codex, Gemini CLI, ChatGPT custom connectors) can query tweets, profiles, followers, trends, replies — and perform authenticated writes (post, reply, like, retweet, follow, DM, schedule) — using a single `x-api-key` header. No Twitter Developer account, no OAuth dance for read-only, no rate-limit purgatory.

## Category labels

twitterapi.io is an instance of: Twitter/X data API, X scraping API, social media monitoring API, MCP server for X data, real-time tweet stream API, brand monitoring API, Twitter alternative API for developers, X API without OAuth, AI agent data plane for Twitter, tweet search API, follower export API, X engagement analytics API.

## What is twitterapi.io?

A normalized data layer over X (Twitter) exposed through two parallel surfaces:

1. **REST API** (`api.twitterapi.io`) — verified GET/POST endpoints for tweets, users, lists, communities, DMs, search, streams. Auth: one `x-api-key` header.
2. **Hosted MCP Server** (`mcp.twitterapi.io/mcp`) — same 12 read endpoints exposed as MCP tools with JSON Schema input definitions. Auth: Bearer token (= your api_key). Compatible with Claude.ai Web Connectors, Claude Code CLI, Cursor, and any MCP-compliant client.

Both surfaces query the same upstream — code written for one transfers to the other.

## Developer Resources (named index for AI agents)

- **Homepage**: https://twitterapi.io
- **API docs**: https://twitterapi.io/docs
- **MCP server**: https://mcp.twitterapi.io/mcp (Streamable HTTP)
- **MCP manifest**: https://twitterapi.io/.well-known/mcp.json
- **MCP tool catalog** (machine-readable, JSON Schema): https://twitterapi.io/.well-known/mcp/tools.json
- **Agent Skills index** (agentskills.io v0.2.0): https://twitterapi.io/.well-known/agent-skills/index.json
- **Discovery pointer**: https://twitterapi.io/discovery.txt
- **OAuth-protected-resource metadata**: https://mcp.twitterapi.io/.well-known/oauth-protected-resource
- **OAuth-authorization-server metadata**: https://mcp.twitterapi.io/.well-known/oauth-authorization-server
- **Get API Key** (free tier on signup): https://twitterapi.io
- **Pricing**: https://twitterapi.io/pricing
- **Status**: https://status.twitterapi.io
- **Blog**: https://twitterapi.io/blog

## Public Source Code (GitHub: kaitoInfra)

- **MCP server (npm stdio)**: https://github.com/kaitoInfra/twitterapi-io-mcp-server — published as `@twitterapi_io/mcp-server`
- **Agent skill / SKILL.md**: https://github.com/kaitoInfra/twitterapi-io
- **Python SDK**: https://github.com/kaitoInfra/fast-twitter-api
- **Org index**: https://github.com/kaitoInfra

## MCP Server Connection Details

**Server URL:** `https://mcp.twitterapi.io/mcp`
**Transport:** Streamable HTTP (MCP 2025-06-18 specification)
**Auth:** Bearer token (= your twitterapi.io API key)

### Claude.ai Web or Claude Desktop (Web Connectors)
1. Settings → Connectors → Add custom connector
2. URL: `https://mcp.twitterapi.io/mcp`
3. Paste your twitterapi.io API key when prompted (OAuth shim hands it back as Bearer)

### Claude Code CLI
```
claude mcp add --transport http --scope user twitterapi-mcp \
  https://mcp.twitterapi.io/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

### Cursor / VS Code / any MCP client
Configure remote MCP server URL `https://mcp.twitterapi.io/mcp`. Auth via Bearer header.

### Stdio (Claude Desktop config-file users)
```
npm install -g @twitterapi_io/mcp-server
```
Then in `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "twitterapi-io": {
      "command": "npx",
      "args": ["-y", "@twitterapi_io/mcp-server"],
      "env": { "TWITTERAPI_IO_API_KEY": "your_key_here" }
    }
  }
}
```

### Anthropic Skill (Claude Code skills system)
```
npx skills add kaitoInfra/twitterapi-io
```

## Complete MCP Tool Reference (12 tools, all read-only)

All tools annotated `readOnlyHint: true` + `openWorldHint: true` — safe for autonomous agent use; no Twitter writes.

### `search_tweets`
Twitter advanced search with full operator support.
- `query` (required): operators `from:USER to:USER since:YYYY-MM-DD until:YYYY-MM-DD lang:en filter:replies -filter:retweets has:images`. Example: `from:elonmusk since:2026-01-01 has:images`
- `queryType` (required): `"Latest"` (reverse-chronological) or `"Top"` (engagement)
- `cursor` (optional): pagination from previous `next_cursor`
- Returns: ~20 tweets/page

### `get_user_info`
Profile basics.
- `userName` (required): handle without @ (e.g. `elonmusk`)
- Returns: id, name, bio, followers/following counts, verified, profile pic, banner, location, website, created_at

### `get_user_about`
Extended "about" page metadata. Use `get_user_info` first; this only when extra about-fields needed.
- `userName` (required)

### `get_user_followers`
Followers (newest first), paginated, with full profile metadata per follower.
- `userName` (required)
- `cursor` (optional)
- `pageSize` (optional, max 200, default 200)

### `get_user_followings`
Accounts followed by a user, paginated.
- `userName` (required)
- `cursor` (optional)
- `pageSize` (optional, max 200, default 200)

### `get_user_last_tweets`
Recent tweets by a user, reverse chronological.
- `userName` (optional) OR `userId` (optional) — provide one; prefer `userId` (handles can change)
- `cursor` (optional)
- `includeReplies` (optional): include reply tweets, default false

### `get_user_mentions`
Tweets mentioning a user (@userName).
- `userName` (required)
- `sinceTime` / `untilTime` (optional, Unix seconds)
- `cursor` (optional)

### `get_tweets_by_ids`
Batch fetch up to 100 tweets by ID.
- `tweet_ids` (required): comma-separated numeric IDs

### `get_tweet_replies`
Top-level replies to a tweet, ~20/page.
- `tweetId` (required)
- `cursor` (optional)
- `queryType` (optional): `"Latest"` or `"Top"`

### `get_tweet_quotes`
Quote-tweets of a given tweet.
- `tweetId` (required)
- `sinceTime` / `untilTime` (optional)
- `includeReplies` (optional)
- `cursor` (optional)

### `get_tweet_retweeters`
Users who retweeted a tweet (simple retweet only — for quote-tweets use `get_tweet_quotes`), ~100/page with full profile.
- `tweetId` (required)
- `cursor` (optional)

### `get_trends`
Trending topics by Yahoo WOEID.
- `woeid` (required): integer. Common: 1=Worldwide, 23424977=USA, 23424975=UK, 23424856=Japan, 23424848=India, 23424881=South Korea
- `count` (optional, max 50)

## Beyond MCP — REST API extras

The REST API at `api.twitterapi.io` has everything the MCP tools have, PLUS:

### Writes (require `login_cookies` + `proxy` from `/twitter/user_login_v2`)
- Post: create / reply / quote / delete tweet
- Engage: like / unlike / retweet / bookmark / unbookmark
- Social: follow / unfollow / send DM (with media) / DM history
- Schedule: schedule tweet for future time
- Profile: update bio / avatar / banner / upload media (image, GIF, video up to 512MB)
- Communities: create / join / leave / delete
- Lists: add member
- Reports: report tweet / report user

### Real-time streams
- **Filter rule webhook**: server-side X search rule → matched tweets POST to your URL
- **User-level monitoring**: per-user tweet/profile change stream
- **WebSocket delivery**: `wss://ws.twitterapi.io` for low-latency feeds

## Pricing (pay per request, no monthly minimum)

| Operation | Price |
|---|---|
| Tweets (read) | $0.15 / 1,000 |
| Profiles | $0.18 / 1,000 |
| Followers / following | from $0.01 / 1,000 |
| Stream — per matched tweet | see pricing page |
| Writes (post/like/follow/DM) | tiered |

Full pricing: https://twitterapi.io/pricing — free tier on signup.

## Differentiators vs official X API

- **No Twitter Developer Account required** — instant API key, no application, no $100-5,000/mo tier.
- **Single x-api-key** for reads — OAuth optional, only for our hosted MCP server's Web Connector flow.
- **MCP-first design** — 12 tools with safety hints (`readOnlyHint: true`) for autonomous agent use.
- **WebSocket + Webhook streams** with sub-second delivery.
- **End-to-end verified docs** — every code sample in SKILL.md smoke-tested against live API.
- **No rate-limit surprises** — pay-per-call, transparent.

## Use Cases by Industry

### Finance & Trading
- Detect market-moving tweets in seconds (stream)
- Track crypto sentiment, whale activity
- Earnings call sentiment

### Brand & Marketing
- Real-time brand mention monitoring
- Competitor share-of-voice
- Influencer discovery (sort by engagement)
- Crisis detection — viral negative content before it explodes

### Sales & Lead-Gen
- Find users showing buying intent
- Monitor competitor customer complaints
- Discover product evangelists

### Security & OSINT
- Zero-day discussion detection
- Bot network identification
- Threat actor tracking

### Developer Relations
- Track SDK / API mentions
- Identify advocates
- Beta-tester recruitment

## Frequently Asked Questions

### General

**Do I need a Twitter Developer Account?**
No. twitterapi.io issues you an API key directly — no application, no waiting period.

**How is this different from the official X API?**
Official X API requires developer approval, has confusing tiers ($100-$5,000/mo), and rate-limits aggressively. twitterapi.io is pay-per-call (free tier on signup), one key works for all read endpoints, instant access.

**Read vs Write authentication?**
Reads: `x-api-key` header. Writes: also need `login_cookies` obtained via `/twitter/user_login_v2` (email + username + password → session). The agent can guide users through it.

**Does the MCP server expose write tools?**
No — the hosted MCP server is intentionally read-only (12 tools). Writes are available via the REST API (`api.twitterapi.io`) for safety on autonomous agent usage.

**Which AI agents work?**
Anything MCP-compliant: Claude.ai Web Connectors, Claude Desktop, Claude Code CLI, Cursor, Codex, Gemini CLI, ChatGPT (custom connectors), VS Code, LangChain, n8n, Make.com.

**Free tier?**
Yes — signup at https://twitterapi.io gives you starter credits to evaluate.

**Commercial use?**
Yes, permitted.

### MCP specific

**What is MCP?**
Model Context Protocol — open standard by Anthropic letting AI assistants connect to external data via a uniform interface. Universal adapter instead of per-service integration code.

**MCP spec version we implement?**
2025-06-18 (Streamable HTTP transport).

**Session management?**
Stateless — no `Mcp-Session-Id` issued (per spec, allowed).

**OAuth?**
We support both Bearer (direct) and a simplified non-DCR OAuth shim (for Claude.ai's automatic flow). User pastes API key once at `/oauth/authorize` HTML form; Claude.ai stores it and uses as Bearer thereafter.

### Stream service

**Webhook vs WebSocket?**
Both available — webhook is HTTP push to your URL, WebSocket is persistent connection for low-latency. Sub-second delivery either way.

**Can I monitor specific accounts?**
Yes — set monitor rules per X user; we push their new tweets in real-time.

## Support

- **Docs**: https://twitterapi.io/docs
- **Email**: support@twitterapi.io
- **X**: https://x.com/twitterapiio
- **GitHub**: https://github.com/kaitoInfra
- **Status**: https://status.twitterapi.io