twitter

Twitter / X（スクリプトモード）

twitterapi.io のエンドポイントへの読み取り専用アクセスです。ツイート、ユーザー、フォロワー、返信、スレッド、引用、記事、トレンドをカバーする 13 の関数を提供します。

すべてのリクエストは core.http_client.proxied_get を経由して sc-proxy を通ります。TWITTER_API_KEY 環境変数はサーバー側で自動的に注入されるため、エージェントのマシンにローカルのキーは不要です。

スクリプトでの使用方法

標準的な呼び出しパターン:

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/twitter")
from exports import twitter_user_info, twitter_user_tweets

profile = twitter_user_info(username="vitalikbuterin")
print(json.dumps(profile, indent=2))

recent = twitter_user_tweets(username="vitalikbuterin")
print(f"got {len(recent.get('tweets', []))} tweets")
EOF

URL からのツイート ID 抽出: x.com/{user}/status/{id} または twitter.com/{user}/status/{id} という URL の最後のパスセグメントがツイート ID です。文字列として渡してください（Python の int では長い ID の精度が失われます）。

関数リファレンス（シグネチャ）

13 の関数はすべて exports.py にあります。戻り値は twitterapi.io からそのまま返される dict です。キーはエンドポイントごとに異なるため、スクリプトを書く前に一度確認してください。

ツイート関連のエンドポイント

関数	説明
twitter_search_tweets(query, cursor=None)	高度な検索。演算子: 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。
twitter_get_tweets(tweet_ids)	ID を指定して 1 件以上のツイートを取得します。tweet_ids = 文字列のリスト（カンマ区切りの文字列も受け付けます）。
twitter_tweet_replies(tweet_id, cursor=None)	ツイートへの返信。
twitter_tweet_retweeters(tweet_id, cursor=None)	リツイートしたユーザー。
twitter_tweet_thread_context(tweet_id)	スレッド全体のコンテキスト（親ツイート＋直接の返信）。
twitter_tweet_quote(tweet_id, cursor=None)	引用ツイート。
twitter_get_article(tweet_id)	長文の X 記事本文。
twitter_get_trends(woeid=None, country=None, category=None, limit=None)	トレンドトピック。すべてのフィルターは任意です。

ユーザー関連のエンドポイント

関数	説明
twitter_user_info(username)	プロフィール: 自己紹介、フォロワー／フォロー数、ツイート数、認証済みかどうか。
twitter_user_tweets(username, cursor=None)	ユーザーの最近のツイート。
twitter_user_followers(username, cursor=None)	フォロワー一覧。
twitter_user_followings(username, cursor=None)	フォロー中のアカウント。
twitter_search_users(query, cursor=None)	名前／キーワードでユーザーを検索します。

username は @ を付けないハンドルです（例: "@elonmusk" ではなく "elonmusk"）。ページネーション: レスポンスに next_cursor が含まれている場合、次の呼び出しでそれを cursor として渡してください。

このスキルの使用が適する場面

• x.com/... または twitter.com/... の URL 全般 → ここから始めてください。web_fetch は使わないでください（Twitter はスクレイパーをブロックします）。
• 単一ツイートの詳細 → twitter_get_tweets([tweet_id])。
• 「@user は最近何を投稿している？」 → twitter_user_tweets。
• KOL の発見／cashtag の言及 → twitter_search_tweets("$SOL min_faves:50")。
• トレンドトピック → twitter_get_trends。

課金とコスト管理（大量・定期利用の前に必ずお読みください）

twitterapi.io はリクエスト単位ではなく、実際に返されたアイテム単位で課金します。また、指定した "max_results" によっても変わりません。sc-proxy の課金 = 返されたアイテム数 × 単価（ツイート 45 / プロフィール 54 / フォロワー 45 クレジット、100k クレジット = $1、上流の 3 倍）。1 リクエストあたり最低 1 アイテムです。

last_tweets / user_tweets の罠: 上流の /twitter/user/last_tweets エンドポイントにはページサイズのパラメータがありません — 常に 1 ページあたり最大 20 ツイートを返します。max_results / pageSize のような調整手段は存在せず、twitter_user_tweets() もそれを受け付けません。つまり「5 件だけ欲しい」場合でも約 20 件を取得し、約 20 件分の課金が発生します。クライアント側で結果を切り詰めてもコストは減りません — 課金は上流のレスポンス時点でプロキシによってすでにカウントされています。

⭐ 「アカウントXの新しいツイート」をポーリングする → last_tweets ではなく search を使う

これは最大かつ最もよくある無駄遣いです。twitter_user_tweets()（上流では last_tweets）にはページサイズのパラメータがなく、新しい投稿がなくても 毎回必ず約20ツイート分のページ全体が課金されます。公式の twitterapi.io ガイドでは、代わりに advanced_search エンドポイントを推奨しており、 これは当スキルではすでに twitter_search_tweets() として公開されています:

# Cheap polling pattern — bills only the tweets actually in the window.
# When NO new tweet exists, the call is billed as 1 item (not 20).
import time
since = int(last_check_unix)
until = int(time.time())
q = f"from:{handle} include:nativeretweets since_time:{since} until_time:{until}"
res = twitter_search_tweets(q)   # queryType defaults to Latest

公式の料金（上流。当プロキシは3倍で課金）:

• ツイートが見つかった場合 → 返されたツイート1件あたり $0.00015
• ツイートが見つからなかった場合 → 呼び出し全体で $0.00015（last_tweets の約20倍に対して）

当社の課金における呼び出しあたりのコストで違いは明らかです:

• last_tweets → 約 $0.009/呼び出し（毎回20ツイート）
• advanced_search の空ウィンドウ → 約 $0.00045/呼び出し（1件）— 約20倍安い

頻度と月額コスト（単一アカウント、上流）: 毎時 $0.11 · 30分 $0.22 · 15分 $0.43 · 5分 $1.30 · 1分 $6.48。

その他のコスト削減の手段

• ID が判明している場合は get_tweets([ids]) を使う — 20件のページではなく、 それらの正確なツイート分だけを支払います。
• フォロワー/フォロー中は返されたプロフィールごとに課金されます（デフォルトの ページは200 → 200件課金）。必要な分だけページネーションしてください。ID のみの グラフ作業には、バルクのフォロワーIDエンドポイント（軽量）を使用してください。
• 検索クエリを絞り込む（min_faves、since_time/until_time、lang）ことで、必要な ページ数を減らせます。

注: twitterapi.io はマネージドのストリーム/Webhook 製品も販売しています。当社は それを購読していません — /oapi/x_user_stream/* や /oapi/tweet_filter/* エンドポイントは使用しないでください。アカウント監視のニーズには、上記の advanced_search ポーリングパターンが、ここでの正しく唯一のアプローチです。

エラーハンドリング

• 402 Credits is not enough → 上流プロキシのクレジットが枯渇しています。ユーザーに チャージするよう伝えてください。リトライしないでください。
• 429 → レート制限中です。ユーザーに通知し、自動リトライしないでください。
• 404 user not found → ハンドルの綴りを確認するよう提案してください。

バージョンポリシー（厳格なルール）

このスキルはスクリプトモード（delivery: script）です。ランタイムツールを 登録しません — エージェントは SKILL.md を read_file し、bash + python3 経由で関数を呼び出す必要があります。レガシーの tools.py / __init__.py ファイルは後方互換性のために残されていますが、もはや推奨されるエントリポイント ではありません。

バージョンアップのルール:

• シグネチャの変更、環境変数の変更、sc-proxy コントラクトの変更 → MAJOR
• 関数の追加、レスポンススキーマの明確化 → MINOR
• バグ修正またはドキュメントのみの変更 → PATCH