twitterapi-io

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

1. Get API key: https://twitterapi.io/dashboard ($0.10 free credits, no CC)
2. 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).
3. 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)

1. GET /twitter/user/info?userName=TARGET -> extract data.id
2. Use that numeric ID in follow/DM/mentions calls

Post tweet with image

1. Upload: POST /twitter/upload_media_v2 -> get media_id
2. 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:

1. POST /oapi/x_user_stream/add_user_to_monitor_tweet for each account
2. 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.