/twitterapi-io

name: twitterapi-io
description: Official skill for twitterapi.io — query Twitter/X data (tweets, profiles, followers, advanced search, trends, spaces, communities, lists) and perform authenticated actions (post, reply, like, retweet, follow, DM) via the twitterapi.io REST API using a single `x-api-key` header — no OAuth. Use when the user needs to scrape, analyze, monitor, or automate X/Twitter without going through the official developer portal.

twitterapi.io

**Official skill** maintained by the [twitterapi.io](https://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

| | | |---|---| | Base URL | `https://api.twitterapi.io` | | Prefix | `/twitter/...` most endpoints; `/oapi/x_user_stream/...` and `/oapi/tweet_filter/...` for real-time monitoring/webhooks; `/oapi/my/info` for balance | | Auth header | `x-api-key: YOUR_KEY` | | Dashboard | https://twitterapi.io/dashboard | | Docs | https://docs.twitterapi.io | | Rate limit | ~200 req/s per client | | Pricing | ~$0.15/1k tweets, ~$0.18/1k profiles, $0.00015 minimum |

⚠️ 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](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](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.**

| Capability | Method | Path & key param | |---|---|---| | User by screen name | GET | `/twitter/user/info?userName=` | | Extended bio | GET | `/twitter/user_about?userName=` | | Batch users by IDs | GET | `/twitter/user/batch_info_by_ids?userIds=` | | Search users | GET | `/twitter/user/search?query=` (**not** `keyword`) | | Recent tweets | GET | `/twitter/user/last_tweets?userName=` (or `userId=`) | | Timeline by ID | GET | `/twitter/user/tweet_timeline?userId=` | | User's articles | GET | `/twitter/user/articles?username=` (**all-lowercase**) | | Mentions of user | GET | `/twitter/user/mentions?userName=` | | Followers | GET | `/twitter/user/followers?userName=&pageSize=200` | | Verified followers | GET | `/twitter/user/verifiedFollowers?user_id=` (**snake**) | | Followings | GET | `/twitter/user/followings?userName=` | | Check follow | GET | `/twitter/user/check_follow_relationship?source_user_name=&target_user_name=` | | Tweets by IDs | GET | `/twitter/tweets?tweet_ids=` (**snake**) | | Tweet replies | GET | `/twitter/tweet/replies?tweetId=` | | Replies (sortable) | GET | `/twitter/tweet/replies/v2?tweetId=&queryType=Latest` | | Quote tweets | GET | `/twitter/tweet/quotes?tweetId=` | | Retweeters | GET | `/twitter/tweet/retweeters?tweetId=` | | Thread context | GET | `/twitter/tweet/thread_context?tweetId=` | | Article content