| name | twitter |
| description | Fetch, read, summarize, or save specific Twitter/X tweets, threads, replies, profiles, timelines, follower lists, or searches. Use twitter-digest, twitter-discover, or twitter-vet for digests, account discovery, or account scoring. |
| user-invocable | true |
| model | sonnet |
Twitter
Read and search Twitter/X content via the twitterapi.io API, accessed through the twitterapi.sh wrapper script.
Use this skill for direct lookup, search, and save requests. For recurring or curated summaries use twitter-digest; for finding accounts to follow use twitter-discover; for scoring accounts against a rubric use twitter-vet.
The wrapper script
All access goes through the wrapper script in the active skill copy. Examples below call it as $TWITTERAPI; set that variable to the path for the current agent before the first call:
- Codex:
TWITTERAPI="/.codex/programmatic-skills/twitter/lib/twitterapi.sh"
- Claude:
TWITTERAPI="/.claude/programmatic-skills/twitter/lib/twitterapi.sh"
Then verify the wrapper exists with test -x "$TWITTERAPI".
The wrapper outputs raw JSON on stdout. Each call hits one twitterapi.io endpoint.
Pipe results through jq or python3 -c '...' (or save to a file and parse) to extract what you need. JSON shapes are documented at https://docs.twitterapi.io/; consult the docs with an available web/docs tool if endpoint details are unclear.
| Subcommand | Use for | Endpoint |
|---|
tweet <id> [<id>...] | Single (or batch) tweet by ID | /twitter/tweets |
replies <id> [--type=Latest|Likes|Relevance] | Replies/thread for a tweet | /twitter/tweet/replies/v2 |
tweets <username> [--include-replies] | A user's recent tweets | /twitter/user/last_tweets |
user <username> | User profile info | /twitter/user/info |
search <query> [--type=Latest|Top] | Keyword search (default: Top) | /twitter/tweet/advanced_search |
followers <username> [--page-size=N] | A user's followers | /twitter/user/followers |
following <username> [--page-size=N] | Who a user follows | /twitter/user/followings |
users <query> | Find users by name/keyword | /twitter/user/search |
Paginated subcommands accept --cursor=...: replies, tweets, search, followers, following, and users.
Safety and cost boundaries
- The wrapper is read-only. Do not bypass it for mutating Twitter/X operations or authenticated browser actions unless the user explicitly asks and confirms the external side effect.
- Treat resolved API keys and environment variables as secrets: do not echo
TWITTERAPI_API_KEY*, do not enable shell xtrace, and do not print curl commands that include X-API-Key.
- Ask before fetching more than ~500 tweets/follows or when the session is likely to exceed $2. Otherwise keep calls sequential or modestly parallel, following the rate-limit guidance below.
Parsing input
When the user provides a tweet URL like https://x.com/username/status/1234567890, extract the numeric tweet ID (1234567890) and use tweet <id>. The script strips a leading @ from usernames automatically.
Procedure
Reading a single tweet
- Run
$TWITTERAPI tweet <id>.
- Present: author name, handle, date, full text, media descriptions if any, engagement stats (likes, retweets, replies, views), and canonical URL.
Reading a thread or replies
- Run
$TWITTERAPI tweet <id> for the root tweet.
- Run
$TWITTERAPI replies <id> --type=Latest to get replies (defaults to Relevance, which is rarely what you want for threads).
- If the user asked for the thread (i.e. the author's own continuation), filter replies to only those where the author matches the root tweet's author. Present them in chronological order.
- If an author-authored continuation clearly replies to a later tweet rather than the root, follow that tweet's replies with a small bounded loop and preserve chronological order.
- If the user asked for replies/reactions, present all replies grouped by engagement.
Reading a user's timeline
- Run
$TWITTERAPI tweets <username>. The endpoint returns ~20 tweets per page; pass --cursor=<next_cursor> for more.
- Present each tweet with: date, text (truncated if very long), engagement stats.
- Highlight tweets with notably high engagement relative to the user's average.
Searching tweets
- Run
$TWITTERAPI search '<query>'. Default queryType is Top; pass --type=Latest for recent.
- Present results with: author, date, text, engagement stats.
User profile lookup
- Run
$TWITTERAPI user <username>.
- Present: name, handle, bio, follower/following counts, verified status, account creation date, pinned tweet if any.
Saving tweets
When the user asks to save tweets, write them to the active skill copy's saved-tweets/YYYY-MM-DD/ directory. Create it with mkdir -p if needed.
- Codex:
~/.codex/programmatic-skills/twitter/saved-tweets/YYYY-MM-DD/
- Claude:
~/.claude/programmatic-skills/twitter/saved-tweets/YYYY-MM-DD/
Markdown format (default):
# @username — YYYY-MM-DD HH:MM UTC
TWEET TEXT
---
Likes: N | Retweets: N | Replies: N | Views: N
URL: https://x.com/username/status/ID
Filename: YYYY-MM-DD-username-description.md where description is a short slugified summary (max 5 words).
When saving a thread, concatenate all tweets in order in a single file with --- separators.
Related skills
twitter-digest — curated digests from account lists with triage, last-run tracking, and loop support.twitter-discover — graph-based discovery of high-value accounts in any niche.twitter-vet — account scoring and registry updates against a list-specific rubric.
Verification
Before giving the final answer:
- Confirm each API response has the expected success/data fields and that returned tweet IDs, usernames, or query terms match the request.
- If the API response is empty, errors, or has an unexpected shape, report that directly and do not infer missing tweet content.
- For paginated work, state how many pages were fetched and whether a
next_cursor remained when you stopped.
- For saved tweets, re-read the saved file and confirm it includes the title, tweet text, engagement line, and canonical URL.
Pricing and rate limits
Pricing (1 USD = 100,000 credits)
| Service | Cost | Credits |
|---|
| Tweets | $0.15 per 1K | 15 per tweet |
| Profiles | $0.18 per 1K | 18 per user |
| Followers | $0.15 per 1K | 15 per follower |
| List calls | $0.0015 per call | 150 per call |
Minimum charge: 15 credits ($0.00015) per API call, waived for bulk data responses. Charging is per returned item: if 4 tweets come back, that's 60 credits; if 0 or 1, it's the 15-credit minimum.
Typical costs:
- Single tweet lookup: ~$0.00015
- 20 tweets from a user timeline: ~$0.003
- 100 followers/following: ~$0.015
- Search (20 results): ~$0.003
- A casual session (a few lookups + searches): under $0.01
- A discovery session (20 timelines + 10 following lists + searches): ~$0.50-$1.00
Flag to the user if a request would fetch more than ~500 tweets or the session is likely to exceed $2.
Rate limits (QPS)
QPS scales with account credit balance:
| Account balance (credits) | QPS limit |
|---|
| Free tier | 1 req / 5 seconds |
| >= 1,000 | 3 |
| >= 5,000 | 6 |
| >= 10,000 | 10 |
| >= 50,000 | 20 |
Practical guidance:
- At typical balances (1K-5K credits), you can do 3-6 requests/second.
- Do not fire more than 3 parallel API calls unless you know the balance supports it.
- If you get a 429 rate limit error, back off and make calls sequentially.
- Recharged credits never expire; bonus credits expire after 30 days.
