1---
2name: twitter
3version: 2.0.2
4description: |
5  Twitter/X data: fetch tweets, search, user profiles, followers, replies, trends.
6 
7  Use for any x.com or twitter.com URL or lookup (e.g. summarize this tweet, recent posts by @vitalikbuterin, search $SOL min_faves:50).
8delivery: script
9metadata:
10  starchild:
11    emoji: "🐦"
12    skillKey: twitter
13    requires:
14      env:
15        - TWITTER_API_KEY
16 
17user-invocable: false
18disable-model-invocation: false
19 
20---
21 
22# Twitter / X (script-mode)
23 
24Read-only access to twitterapi.io endpoints. 13 functions covering tweets,
25users, followers, replies, threads, quotes, articles, and trends.
26 
27All requests go through sc-proxy via `core.http_client.proxied_get`. The
28`TWITTER_API_KEY` env var is auto-injected server-side, no local key needed
29on the agent machine.
30 
31## Script Usage
32 
33Standard invocation pattern:
34 
35```bash
36python3 - <<'EOF'
37import sys, json
38sys.path.insert(0, "/data/workspace/skills/twitter")
39from exports import twitter_user_info, twitter_user_tweets
40 
41profile = twitter_user_info(username="vitalikbuterin")
42print(json.dumps(profile, indent=2))
43 
44recent = twitter_user_tweets(username="vitalikbuterin")
45print(f"got {len(recent.get('tweets', []))} tweets")
46EOF
47```
48 
49Tweet ID extraction from URL: the last path segment of any
50`x.com/{user}/status/{id}` or `twitter.com/{user}/status/{id}` URL is the
51tweet ID. Pass it as a string (Python int will lose precision on long IDs).
52 
53## Function Reference (signatures)
54 
55All 13 functions live in `exports.py`. Returns are dicts straight from
56twitterapi.io — keys vary per endpoint, inspect once before scripting.
57 
58### Tweet endpoints
59 
60| Function | Description |
61|---|---|
62| `twitter_search_tweets(query, cursor=None)` | Advanced search. Operators: `from:user`, `to:user`, `#tag`, `$cashtag`, `lang:en`, `has:media`, `has:links`, `is:reply`, `min_faves:N`, `since:YYYY-MM-DD`, `until:YYYY-MM-DD`. |
63| `twitter_get_tweets(tweet_ids)` | Fetch one or more tweets by ID. `tweet_ids` = list of strings (also accepts comma-string). |
64| `twitter_tweet_replies(tweet_id, cursor=None)` | Replies to a tweet. |
65| `twitter_tweet_retweeters(tweet_id, cursor=None)` | Users who retweeted. |
66| `twitter_tweet_thread_context(tweet_id)` | Full thread context (parents + direct replies). |
67| `twitter_tweet_quote(tweet_id, cursor=None)` | Quote tweets. |
68| `twitter_get_article(tweet_id)` | Long-form X article body. |
69| `twitter_get_trends(woeid=None, country=None, category=None, limit=None)` | Trending topics; all filters optional. |
70 
71### User endpoints
72 
73| Function | Description |
74|---|---|
75| `twitter_user_info(username)` | Profile: bio, follower/following counts, tweet count, verified. |
76| `twitter_user_tweets(username, cursor=None)` | User's recent tweets. |
77| `twitter_user_followers(username, cursor=None)` | Follower list. |
78| `twitter_user_followings(username, cursor=None)` | Accounts followed. |
79| `twitter_search_users(query, cursor=None)` | Search users by name/keyword. |
80 
81`username` is the handle WITHOUT `@` (e.g. `"elonmusk"`, not `"@elonmusk"`).
82Pagination: when a response includes `next_cursor`, pass it back as `cursor`
83on the next call.
84 
85## When to use this skill
86 
87- ANY `x.com/...` or `twitter.com/...` URL → start here, NOT `web_fetch`
88  (Twitter blocks scrapers).
89- Single tweet detail → `twitter_get_tweets([tweet_id])`.
90- "What's @user been posting?" → `twitter_user_tweets`.
91- KOL discovery / cashtag mentions → `twitter_search_tweets("$SOL min_faves:50")`.
92- Trending topics → `twitter_get_trends`.
93 
94## Billing & cost control (READ before bulk/scheduled use)
95 
96twitterapi.io bills **per item actually returned**, not per request and NOT by
97any "max_results" you ask for. sc-proxy charges = returned-item-count × unit
98(tweets 45 / profiles 54 / followers 45 credits; 100k credits = $1; 3× upstream).
99Min 1 item per request.
100 
101**The `last_tweets` / `user_tweets` trap:** the upstream
102`/twitter/user/last_tweets` endpoint has **no page-size parameter** — it always
103returns up to **20 tweets per page**. There is no `max_results` / `pageSize`
104lever, and `twitter_user_tweets()` does not accept one. So "I only need 5" still
105fetches and **bills for ~20**. Slicing the result client-side does NOT save
106money — the charge is already counted at the proxy from the upstream response.
107 
108### ⭐ Polling for "new tweets from account X" → use search, NOT last_tweets
109 
110This is the biggest, most common waste. `twitter_user_tweets()` (upstream
111`last_tweets`) has **no page-size param** and always bills a full ~20-tweet
112page every call, even when nothing new was posted. The official twitterapi.io
113guide recommends the **advanced_search** endpoint instead, which our skill
114already exposes as `twitter_search_tweets()`:
115 
116```python
117# Cheap polling pattern — bills only the tweets actually in the window.
118# When NO new tweet exists, the call is billed as 1 item (not 20).
119import time
120since = int(last_check_unix)
121until = int(time.time())
122q = f"from:{handle} include:nativeretweets since_time:{since} until_time:{until}"
123res = twitter_search_tweets(q)   # queryType defaults to Latest
124```
125 
126Official pricing (upstream; our proxy bills 3×):
127- tweets found → $0.00015 per returned tweet
128- **no tweets found → $0.00015 for the whole call** (vs last_tweets' ~20× that)
129 
130Per-call cost in our billing makes the difference obvious:
131- `last_tweets` → ~$0.009/call (20 tweets every time)
132- `advanced_search` empty window → ~$0.00045/call (1 item) — **~20× cheaper**
133 
134Frequency vs monthly cost (single account, upstream): hourly $0.11 · 30min
135$0.22 · 15min $0.43 · 5min $1.30 · 1min $6.48.
136 
137### Other cost levers
138- **Use `get_tweets([ids])`** when IDs are known — pay only for those exact
139  tweets, not a 20-item page.
140- **Followers/followings** bill per returned profile (default page 200 → 200
141  billed). Only paginate as far as needed. For ID-only graph work use the
142  bulk followers-IDs endpoint (lightweight).
143- **Tighten search queries** (min_faves, since_time/until_time, lang) so fewer
144  pages are needed.
145 
146> Note: twitterapi.io also sells a managed stream/webhook product. **We do NOT
147> subscribe to it** — do not use the `/oapi/x_user_stream/*` or
148> `/oapi/tweet_filter/*` endpoints. For any account-monitoring need, the
149> advanced_search polling pattern above is the correct and only approach here.
150 
151## Error handling
152 
153- `402 Credits is not enough` → upstream proxy credits exhausted; tell user
154  to top up. Don't retry.
155- `429` → rate limited; surface to user, don't auto-retry.
156- `404 user not found` → suggest verifying the handle spelling.
157 
158## Version Policy (hard rule)
159 
160This skill is **script-mode** (`delivery: script`). It does NOT register
161runtime tools — agent must `read_file` SKILL.md and call functions via
162`bash` + `python3`. The legacy `tools.py` / `__init__.py` files are kept
163for backward compatibility but are no longer the preferred entry point.
164 
165Bump rules:
166- Any signature change, env-var change, or sc-proxy contract change → MAJOR
167- New function added, response schema clarified → MINOR
168- Bug fix or doc-only change → PATCH
169