twitterapi-io

twitterapi.io

Official skill maintained by the twitterapi.io team. Paths, parameters, and body fields in this skill are verified against the live backend.

When to use this skill

Trigger when the user wants any of:

• Fetch tweets, user profiles, followers/following, trends, replies, quote-tweets, retweeters, articles
• Advanced tweet search (X operators, date ranges, engagement filters)
• Monitor users or filter rules in near real time
• Post / delete / like / retweet / bookmark / quote-tweet / reply / follow / DM / schedule tweets
• Update profile / avatar / banner, upload media
• Create/join/leave communities, manage lists, report content
• Anything involving twitterapi.io, api.twitterapi.io, x-api-key, login_cookies, or the X API without OAuth

Core facts

⚠️ Two rules that catch people

Rule 1 — Parameter naming is per-endpoint

No universal snake_case or camelCase rule. Examples (all correct):

• /twitter/user/followers?userName= (camel)
• /twitter/user/verifiedFollowers?user_id= (snake)
• /twitter/user/articles?username= (all-lowercase)
• /twitter/tweets?tweet_ids= (snake) but /twitter/tweet/replies?tweetId= (camel)
• /twitter/list/tweets_timeline?listId= (camel) but /twitter/list/members?list_id= (snake)

Copy the exact parameter name from references/endpoints.md. Don't normalize.

Rule 2 — Writes need three things in body, not two

Every write endpoint requires:

1. login_cookies (plural, not login_cookie) — base64-encoded JSON from /twitter/user_login_v2
2. proxy (HTTP/SOCKS proxy URL — configure in dashboard)
3. Action-specific fields, almost always snake_case (tweet_id, user_id)

Plus key field-name traps:

• create_tweet_v2 text field is tweet_text (not text); reply field is reply_to_tweet_id (not in_reply_to_tweet_id)
• update_profile_v2 uses description (not bio)
• bookmarks_v2 uses count (not pageSize)
• send_dm_to_user: user_id + text; optional media_id (singular)
• Monitoring add uses x_user_name; remove uses id_for_user (different fields per endpoint!)

See references/write-operations.md for full body shapes.

Rule 3 — Response shape varies per endpoint

• data-wrapped: user/info, user_about, last_tweets, tweet_timeline, trends, check_follow_relationship → r["data"]["..."]
• Flat with envelope: followers, followings, replies, mentions, community/tweets → r["followers"], r["tweets"], etc.
• Flat without envelope: advanced_search, thread_context, user/search, get_tweets_from_all_community → just {tweets[], has_next_page, next_cursor}
• Named top-level field: community/info → r["community_info"]; batch_info_by_ids → r["users"]
• oapi/my/info → {recharge_credits, total_bonus_credits} (no status wrapper)

Prefer defensive access: r.get("tweets", r.get("data", {}).get("tweets", [])).

Security

Never hardcode the API key. Read from env TWITTERAPI_IO_KEY. If missing, ask the user.

Minimal working example

curl -s "https://api.twitterapi.io/twitter/user/info?userName=elonmusk" \
  -H "x-api-key: $TWITTERAPI_IO_KEY"

import os, requests

BASE = "https://api.twitterapi.io"
HEADERS = {"x-api-key": os.environ["TWITTERAPI_IO_KEY"]}

r = requests.get(f"{BASE}/twitter/user/info",
                 headers=HEADERS,
                 params={"userName": "elonmusk"},
                 timeout=30)
r.raise_for_status()
d = r.json()["data"]
print(f"{d['userName']} — {d['followers']:,} followers")

Endpoint quick reference

Reads (API key only). Exact param names — copy as shown.

Real-time monitoring (/oapi/x_user_stream/*). Field names differ per endpoint!

Webhook filter rules (/oapi/tweet_filter/*):

Writes — require login_cookies + proxy in body. login_cookies is base64(json(cookie_dict)) from /twitter/user_login_v2.

For exact param lists, response shapes, and edge cases see references/endpoints.md.

Recurring patterns

Cursor pagination — use has_next_page

def iter_followers(user_name):
    cursor = ""
    while True:
        r = requests.get(f"{BASE}/twitter/user/followers",
                         headers=HEADERS,
                         params={"userName": user_name, "cursor": cursor, "pageSize": 200},
                         timeout=30).json()
        yield from r.get("followers", [])
        if not r.get("has_next_page"):
            break
        cursor = r.get("next_cursor") or ""

Error handling

# FastAPI-style 4xx/5xx
{ "detail": "tweet_id is required" }
{ "detail": [{"type":"missing","loc":["body","file"]}] }  # 422 on multipart

# Semantic 200 errors
{ "status": "error", "msg": "No active monitoring subscription" }

• 401 → bad x-api-key or expired login_cookies
• 402 → top up balance at dashboard
• 429 → rate-limited; exponential backoff
• 400/422 → read detail — it names the missing/wrong field
• 500 → transient; retry with jitter. If repeated, the param name is wrong

Cost awareness

Before a loop that could paginate for a long time (followers of a mega-account, years of advanced search), estimate cost up front and confirm with the user if it could exceed a few dollars. A 100M-follower crawl is $15k+ at $0.15/1k.

Anti-patterns

• Do not assume a universal param-casing rule — check endpoints.md
• Do not use login_cookie (singular) — it's login_cookies plural
• Do not forget proxy in write bodies — every write requires it
• Do not send text for create_tweet_v2 — use tweet_text
• Do not use bio in update_profile_v2 — use description
• Do not use in_reply_to_tweet_id for create_tweet_v2 — it's reply_to_tweet_id
• Do not send JSON to upload_media_v2 / update_avatar_v2 / update_banner_v2 — they're multipart/form-data
• Do not use pageSize for bookmarks_v2 — it's count
• Do not send user_id to monitoring add — it's x_user_name; remove uses id_for_user
• Do not log or commit API keys, login_cookies, proxies, or totp_secret
• Do not use developer.twitter.com / official X OAuth — this API replaces them
• Do not poll /user/last_tweets for "real-time" — use /oapi/tweet_filter/add_rule + webhook