TwitterAPI.io

Interact with Twitter/X via TwitterAPI.io — search tweets, get user info, post tweets, like, retweet, follow, send DMs, and more. Covers all 65 endpoints (V2...

Security Scan

The skill's documentation and runtime instructions align with its Twitter proxy purpose, but the package metadata omits the API key and other sensitive requirements (login cookies, user credentials, residential proxy), which is an incoherence users should understand before installing.

Purpose & Capability

The skill's name/description (TwitterAPI.io integration) matches the documented endpoints and actions (read/write/webhook/stream). However, the skill metadata declares no required environment variables or primary credential, while SKILL.md explicitly requires an API key (X-API-Key via $TWITTERAPI_IO_KEY) and, for write actions, user login credentials and residential proxy settings. The missing declaration of the API key in metadata is an inconsistency to be aware of.

Instruction Scope

SKILL.md is an instruction-only runtime guide with many curl examples. It directs the agent to make requests only to the api.twitterapi.io endpoints and to use an API key header. For write operations it instructs obtaining/login with user credentials (email/password/TOTP) and using `login_cookies` plus residential proxies. That expands the sensitivity of data involved (account credentials, TOTP, proxy credentials, cookies). The instructions do not ask the agent to read unrelated system files or exfiltrate data to unexpected hosts, but they do require handling highly sensitive secrets which the agent or user must supply.

Install Mechanism

No install spec or code files are executed; the skill is instruction-only. This minimizes installation-time risk (nothing downloaded or executed), though the SKILL.md does describe using curl/file uploads at runtime (which run only if the agent/user executes them).

Credentials

Metadata lists no required environment variables, but SKILL.md repeatedly refers to $TWITTERAPI_IO_KEY and instructs storing it in a .env or shell config. It also requires (for write actions) login credentials, TOTP secrets, and residential proxy credentials. Those are high-sensitivity items and should have been declared. The absence of declared env vars in the registry metadata is a mismatch and reduces transparency about what secrets the skill will need.

Persistence & Privilege

The skill does not request always:true or any persistent privileges; it is user-invocable and the agent may call it autonomously (default). There is no install-time persistence or modification of other skills indicated.

What to consider before installing

This skill appears to be a comprehensive instruction-only wrapper for the third-party service twitterapi.io and will let an agent read and perform actions on X/Twitter. Before installing: (1) understand that SKILL.md requires an API key (X-API-Key) even though the registry metadata does not declare it — plan to provide TWITTERAPI_IO_KEY securely (prefer secret storage rather than pasting into chat). (2) For any write actions the skill requires very sensitive data: your Twitter account credentials, 2FA/TOTP secrets, and residential proxy credentials (or cookies). Only provide those if you trust the downstream provider (twitterapi.io) and understand billing (the skill documents a credit-based pricing). (3) Because metadata omitted the API key requirement, double-check any platform UI for secret prompts and avoid pasting credentials into conversation text or ephemeral logs. (4) If you only need read-only info, consider limiting the skill to read endpoints and avoid invoking login/login-cookie flows. (5) Verify the provider (twitterapi.io) independently (homepage, terms, privacy, billing) before handing over account or payment information. If you want, I can list the exact sensitive fields the skill will ask for and suggest safer minimal setups (e.g., read-only API key usage) or alternative official APIs.

TwitterAPI.io skill v3.6.0

Access Twitter/X data and perform actions via TwitterAPI.io REST API. Use TwitterAPI.io REST API for read, write, webhook, and stream operations.

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
Community info	20	$0.0002
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

---

API Version Note

All V1 endpoints have been removed from the API. Use V2 (_v2 suffix) or V3 (_v3 suffix) endpoints for write operations. V2 requires login_cookies (from user_login_v2) + residential proxy. V3 requires user_name-based auth (from user_login_v3) -- async operations, no proxy needed for most actions.

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": null,
  "inReplyToUserId": null,
  "inReplyToUsername": null,
  "conversationId": "1234567890",
  "displayTextRange": [0, 280],
  "isLimitedReply": false,
  "author": { "...User Object..." },
  "entities": {
    "hashtags": [{ "text": "AI", "indices": [10, 13] }],
    "urls": [{ "display_url": "example.com", "expanded_url": "https://example.com", "url": "https://t.co/xxx" }],
    "user_mentions": [{ "id_str": "123", "name": "Someone", "screen_name": "someone" }]
  },
  "quoted_tweet": null,
  "retweeted_tweet": null
}

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,
  "favouritesCount": 50000,
  "mediaCount": 2000,
  "statusesCount": 30000,
  "createdAt": "Tue Jun 02 20:12:29 +0000 2009",
  "pinnedTweetIds": ["1234567890"],
  "isAutomated": false,
  "possiblySensitive": false,
  "profile_bio": {
    "description": "Bio text...",
    "entities": {
      "description": { "urls": [] },
      "url": { "urls": [{ "display_url": "example.com", "expanded_url": "https://example.com" }] }
    }
  }
}

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 (34 endpoints), consult references/read-endpoints.md
• For WRITE V2 + V3 endpoint documentation (25 endpoints), consult references/write-endpoints.md
• For Webhook and Stream endpoint documentation (6 endpoints), consult references/webhook-stream-endpoints.md
• For the complete endpoint index table (all 65 endpoints), consult references/endpoint-index.md

---

X/Twitter platform degradation notice (March 2026)

CRITICAL: Around March 5, 2026, Twitter/X disabled or degraded several advanced search features due to high platform usage. This affects ALL Twitter API providers (not just TwitterAPI.io) because TwitterAPI.io proxies Twitter's own search infrastructure.

What's broken

Feature	Status	Impact
since:DATE / until:DATE in search	DEGRADED	Returns incomplete results (often only 7-20 tweets per query regardless of actual volume)
Search pagination	BROKEN	Cursor-based pagination returns the SAME page of results repeatedly instead of advancing
since_time:UNIX / until_time:UNIX	WORKS	Alternative date format using Unix timestamps -- returns correct date range
within_time:Nh	WORKS	Relative time filter (e.g., within_time:72h)
get_user_last_tweets pagination	WORKS	User timeline cursor pagination is unaffected
get_user_mentions sinceTime/untilTime	WORKS	Server-side Unix timestamp parameters (not search operators)
Webhook filter rules	WORKS	Real-time collection unaffected (but webhook URL may be lost during API key rotation)

Workarounds for date-range queries

Instead of (broken):

$BTC since:2026-03-06_00:00:00_UTC until:2026-03-07_00:00:00_UTC

Use (working):

$BTC since_time:1741219200 until_time:1741305600

Convert dates to Unix timestamps: date -d "2026-03-06T00:00:00Z" +%s or use Python: int(datetime(2026,3,6,tzinfo=timezone.utc).timestamp())

Pagination workaround: Since pagination is broken, use hourly time windows instead of paginating through a large result set. Each 1-hour window returns a unique set of ~7-16 tweets (page 1 only). This gives ~250 unique tweets per coin per day across 24 windows.

For user timelines: Use GET /twitter/user/last_tweets with cursor pagination (works normally). Paginate backwards through the user's timeline, then client-side filter by createdAt date. This completely bypasses search operators.

Webhook URL gotcha

When a TwitterAPI.io API key is rotated (e.g., after account data reset), the webhook filter rules may be restored but the webhook URL is NOT automatically restored. You must manually re-set the webhook URL in the dashboard at https://twitterapi.io/tweet-filter-rules after any key rotation event.

Monitoring tip: Check that collection_type='webhook' tweets are still arriving. If rules are active but zero webhook tweets arrive for 30+ minutes, verify the webhook URL is configured.

---

Twitter search syntax (for query param in advanced_search)

Operator	Example	Description	Status (Mar 2026)
from:	from:elonmusk	Tweets by user	Working
to:	to:elonmusk	Replies to user	Working
"..."	"exact phrase"	Exact match	Working
OR	cat OR dog	Either term	Working
-	-spam	Exclude term	Working
since: / until:	since:2026-01-01_00:00:00_UTC	Date range (UTC)	DEGRADED -- use since_time: instead
since_time: / until_time:	since_time:1741219200	Date range (Unix timestamp)	Working
within_time:	within_time:24h	Relative time window	Working
min_faves:	min_faves:100	Min likes	Working
min_retweets:	min_retweets:50	Min RTs	Working
filter:media	filter:media	Has media	Working
filter:links	filter:links	Has links	Working
lang:	lang:en	Language	Working
is:reply	is:reply	Only replies	Working
-is:retweet	-is:retweet	Exclude RTs	Working

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="".

Known issues (March 2026):

• advanced_search pagination is broken -- returns the same results on every page. Use hourly time windows (1 page per window) instead of deep pagination.
• get_user_last_tweets pagination works normally -- cursor advances through the user's timeline chronologically.
• has_next_page may return true even when no more data exists (Twitter API limitation). If a subsequent request returns empty or identical 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	Check correct path in this doc

---

Common workflows

Get user ID from username (needed for follow, DM)

1. GET /twitter/user/info?userName=TARGET -> extract data.id
2. Use that numeric ID in follow/DM calls Note: get_user_mentions accepts userName directly -- no ID lookup needed.

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.