| name | twitterapi-io |
| description | Interact with Twitter/X via TwitterAPI.io — search tweets, get user info, post tweets, like, retweet, follow, send DMs, and more. Covers all 59 endpoints. Use when the user wants to read or write Twitter data. |
| metadata | {"version":"3.2.0","updated":"2026-02-13T00:00:00.000Z","author":"dorukardahan"} |
TwitterAPI.io skill v3.1.0
Access Twitter/X data and perform actions via TwitterAPI.io REST API.
Two API generations: v1 (deprecated) and v2 (current, recommended).
Docs: https://docs.twitterapi.io | Dashboard: https://twitterapi.io/dashboard
Setup
- Get API key: https://twitterapi.io/dashboard ($0.10 free credits, no CC)
- Store the key in a
.env file or your shell's secure config (do not use raw export with the actual key in the terminal -- it gets saved to shell history).
- For write actions, you also need
login_cookies from v2 login + residential proxy.
Base URL: https://api.twitterapi.io
Auth header: X-API-Key: $TWITTERAPI_IO_KEY (all requests)
Pricing (credit-based, 1 USD = 100,000 credits)
| Resource | Credits | Approx $/1K |
|---|
| Tweets (per returned tweet) | 15 | $0.15 |
| Profiles (per returned profile) | 18 | $0.18 |
| Profiles batch 100+ (per profile) | 10 | $0.10 |
| Followers (per returned follower) | 15 | $0.15 |
| Verified followers (per follower) | 30 | $0.30 |
| Minimum per API call | 15 | $0.00015 |
| List endpoint calls | 150 | $0.0015 |
| Check follow relationship | 100 | $0.001 |
| Get article | 100 | $0.001 |
| Write actions (tweet, like, RT, follow) | 200-300 | $0.002-0.003 |
| Login | 300 | $0.003 |
Note: If the API returns 0 or 1 item, you are still charged the minimum (15 credits).
QPS (rate limits) -- balance-based
| Account Balance (Credits) | QPS Limit |
|---|
| < 1,000 (free tier) | 1 req / 5 sec |
| >= 1,000 | 3 |
| >= 5,000 | 6 |
| >= 10,000 | 10 |
| >= 50,000 | 20 |
V1 vs V2 endpoints
| Feature | V1 (deprecated) | V2 (current) |
|---|
| Login | /twitter/login_by_email_or_username + /twitter/login_by_2fa | /twitter/user_login_v2 |
| Tweet | /twitter/create_tweet | /twitter/create_tweet_v2 |
| Like | /twitter/like_tweet | /twitter/like_tweet_v2 |
| Retweet | /twitter/retweet_tweet | /twitter/retweet_tweet_v2 |
| Upload | /twitter/upload_image | /twitter/upload_media_v2 |
| Auth param | auth_session | login_cookies |
| Pricing | $0.001/call | $0.002-0.003/call |
V1 cookies do NOT work with v2 endpoints and vice versa. Always use v2.
login_cookie vs login_cookies -- API Inconsistency
The API has an inconsistency in naming:
user_login_v2 response returns the field as login_cookie (singular)- All v2 action endpoints expect the field as
login_cookies (plural)
Always use login_cookies (plural) in request bodies. The value is the same string.
Response schemas
Tweet object (from search, replies, etc.)
{
"type": "tweet",
"id": "1234567890",
"url": "https://x.com/user/status/1234567890",
"text": "Tweet content...",
"source": "Twitter Web App",
"retweetCount": 5,
"replyCount": 2,
"likeCount": 42,
"quoteCount": 1,
"viewCount": 1500,
"bookmarkCount": 3,
"createdAt": "Sun Feb 08 12:00:00 +0000 2026",
"lang": "en",
"isReply": false,
"inReplyToId"
User object
{
"type": "user",
"id": "999888777",
"userName": "elonmusk",
"name": "Elon Musk",
"url": "https://x.com/elonmusk",
"isBlueVerified": true,
"verifiedType": "none",
"profilePicture": "https://pbs.twimg.com/...",
"coverPicture": "https://pbs.twimg.com/...",
"description": "Bio text...",
"location": "Mars",
"followers": 200000000,
"following": 800,
"canDm": false
Paginated list response
{
"tweets": [ "...array of Tweet Objects..." ],
"has_next_page": true,
"next_cursor": "cursor_string...",
"status": "success",
"msg": null
}
Endpoint reference
For detailed endpoint documentation with curl examples, consult the reference files:
- For READ endpoint documentation (30 endpoints), consult
references/read-endpoints.md
- For WRITE V2 endpoint documentation (18 endpoints), consult
references/write-endpoints.md
- For Webhook and Stream endpoint documentation (7 endpoints), consult
references/webhook-stream-endpoints.md
- For Deprecated V1 endpoint list (6 endpoints), consult
references/deprecated-v1.md
- For the complete endpoint index table (all 59 endpoints), consult
references/endpoint-index.md
Twitter search syntax (for query param in advanced_search)
| Operator | Example | Description |
|---|
from: | from:elonmusk | Tweets by user |
to: | to:elonmusk | Replies to user |
"..." | "exact phrase" | Exact match |
OR | cat OR dog | Either term |
- | -spam | Exclude term |
since: / until: | since:2026-01-01_00:00:00_UTC | Date range (UTC) |
min_faves: | min_faves:100 | Min likes |
min_retweets: | min_retweets:50 | Min RTs |
filter:media | filter:media | Has media |
filter:links | filter:links | Has links |
lang: | lang:en | Language |
is:reply | is:reply | Only replies |
-is:retweet | -is:retweet | Exclude RTs |
More examples: https://github.com/igorbrigadir/twitter-advanced-search
Pagination
Most list endpoints return:
{ "has_next_page": true, "next_cursor": "cursor_string..." }
Pass cursor=NEXT_CURSOR to get next page. First page: omit cursor or cursor="".
Warning: has_next_page may sometimes return true even when no more data exists (Twitter API limitation). If a subsequent request returns empty results, stop paginating.
Error handling
{ "status": "error", "msg": "Error message" }
| Error | Cause | Fix |
|---|
| Invalid API key | Wrong or missing X-API-Key header | Check key in dashboard |
| Invalid login_cookie | Expired or faulty cookie | Re-login via user_login_v2 with valid totp_secret |
| 400 on v2 actions | Faulty cookie from login without proper totp_secret | Re-login with 16-char string totp_secret |
| Proxy error | Bad proxy format or dead proxy | Format: http://user:pass@host:port, use residential |
| Rate limited | Exceeded QPS for your balance tier | Back off, add balance for higher QPS |
| Account suspended | Twitter account banned | Use different account |
| 404 on endpoint | Wrong path or v1 endpoint removed | Check correct path in this doc |
Common workflows
Get user ID from username (needed for follow, DM, mentions)
GET /twitter/user/info?userName=TARGET -> extract data.id- Use that numeric ID in follow/DM/mentions calls
Post tweet with image
- Upload:
POST /twitter/upload_media_v2 -> get media_id
- Tweet:
POST /twitter/create_tweet_v2 with media_ids: ["media_id"]
Reply to a tweet
POST /twitter/create_tweet_v2 with tweet_text + reply_to_tweet_id
Quote tweet
POST /twitter/create_tweet_v2 with tweet_text + attachment_url (full tweet URL)
Post to community
POST /twitter/create_tweet_v2 with tweet_text + community_id
Monitor accounts for new tweets (cheapest method)
Use Stream endpoints instead of polling /twitter/user/last_tweets:
POST /oapi/x_user_stream/add_user_to_monitor_tweet for each account- Set up webhook to receive notifications
MCP server
claude mcp add twitterapi-io -- npx -y twitterapi-io-mcp
npm: https://www.npmjs.com/package/twitterapi-io-mcp
GitHub: https://github.com/dorukardahan/twitterapi-io-mcp
Also available: twitterapi-docs MCP server for querying this documentation programmatically.
Important notes
- Read endpoints need only API key. No Twitter account needed.
- Write endpoints need
login_cookies from v2 login + residential proxy.
- V2 cookies only work with v2 endpoints (
_v2 suffix).
- 2FA strongly recommended -- use 16-character string
totp_secret for reliable login.
- Proxy mandatory for all write actions. Use high-quality residential proxies.
- Credits never expire once recharged. Bonus credits valid 30 days.
