SocialData APIの罠：フォロワー一覧に「最新ツイート」が含まれない問題と対処法

半年後の自分が同じ罠を踏まないよう、技術的な誤算と学びを開発ログとして残すメモです。

背景：なぜデータが空なのか

X（旧 Twitter）のフォロー関係を扱う自作アプリで、一覧に「最終投稿日時」を出そうとしたところ、本番データはほぼすべて「—（空）」でした。最初は実装バグを疑い、user.status.created_at 周りの型（Optional）を追いかけていました。

しかし根本原因はコードの細部ではなく、利用している API のレスポンス仕様そのものにありました。ここを取り違えると、リリース後に「データが来ない」事実だけが残り、調査に時間がかかります。

原因：ドキュメントの Example を一次ソースにする

Twitter API v1.1 の感覚では、「ユーザーオブジェクトには最新ツイート（status）が紐づくことがある」と考えがちです。一方、SocialData の Get User Followers（GET /twitter/followers/list）の 200 レスポンスの Example では、users[] はプロフィール情報までに留まり、埋め込み status は含まれていません。フォロー一覧・単体プロフィール・users-by-ids の例も同様に、直近ツイートは別カテゴリのデータとして切り離されています。

教訓： サードパーティ API では、TypeScript の型や過去の API の記憶だけで仮説を立てず、公式ドキュメントのレスポンス Example と Pricing の課金単位を設計の一次ソースにする。型にフィールドがあっても、実レスポンスに必ず含まれるわけではない。

解決の方向性：最終投稿を取るなら別エンドポイントとコスト設計

正攻法としては、例えば GET /twitter/user/{user_id}/tweets を別途呼び、1 ページ目の先頭ツイートの tweet_created_at を「直近の投稿日時」として使う形がドキュメントと整合します（鍵アカウントは取得できない等の制約あり）。

フォロワー／フォロー一覧の取得とはエンドポイントも課金単位も別になるため、「一覧 API だけで最後まで済ませる」発想がそもそも噛み合わない、というのが設計上のポイントです。

コストのレンジ（試算）

Pricing 上、ツイート系は 取得したツイートあたり $0.0002 という整理です。タイムラインは 1 リクエストで複数件（例：約 20 件前後）返る説明があるため、課金が「先頭 1 件」に留まるのか「ページ内すべて」に乗るのかは、実リクエストとダッシュボードで要確認です。

スキャン 1 回あたりの追加分のみ（フォロー／フォロワー一覧の課金は別枠）：

ユニーク人数の目安楽観（1 ツイート分/人）悲観（約 20 ツイート分/人）
1,500 人約 $0.30約 $6
約 1,870 人約 $0.37約 $7.5
7,000 人約 $1.40約 $28
25,000 人約 $5約 $100

判断メモ（未来の自分へ）

楽観寄りの試算では、1,500 人規模でスキャン 1 回あたり約 $0.30 のオーダーがこの機能だけで上乗せされます。UX に見合うかを先に問う必要があります。同じ前提で毎日自動実行すると、ざっくり月 $9 前後のイメージになります（単純に 30 倍）。

個人ツールであれば、必要なときだけオンデマンドでタイムライン API を回す、あるいは列自体を廃止する、のほうがコストとレート制限の両面で現実的、という整理に落ち着きます。

ここは試算に基づく方針メモです。実装はリリースごとに変わりうるため、数字は都度 Pricing とダッシュボードで確認してください。

まとめ