twitter

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.

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

1. Run $TWITTERAPI tweet <id>.
2. 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

1. Run $TWITTERAPI tweet <id> for the root tweet.
2. Run $TWITTERAPI replies <id> --type=Latest to get replies (defaults to Relevance, which is rarely what you want for threads).
3. 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.
4. 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.
5. If the user asked for replies/reactions, present all replies grouped by engagement.

Reading a user's timeline

1. Run $TWITTERAPI tweets <username>. The endpoint returns ~20 tweets per page; pass --cursor=<next_cursor> for more.
2. Present each tweet with: date, text (truncated if very long), engagement stats.
3. Highlight tweets with notably high engagement relative to the user's average.

Searching tweets

1. Run $TWITTERAPI search '<query>'. Default queryType is Top; pass --type=Latest for recent.
2. Present results with: author, date, text, engagement stats.

User profile lookup

1. Run $TWITTERAPI user <username>.
2. 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:

1. Confirm each API response has the expected success/data fields and that returned tweet IDs, usernames, or query terms match the request.
2. If the API response is empty, errors, or has an unexpected shape, report that directly and do not infer missing tweet content.
3. For paginated work, state how many pages were fetched and whether a next_cursor remained when you stopped.
4. 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.