TwexAPI で X List の投稿を取得する方法
X Lists が便利なのは、誰かがすでに編集上の選別を一部済ませているからです。List は市場、取材領域、コミュニティ、競合セットなどに沿ってアカウントをまとめるため、広いキーワード検索よりもノイズの少ないフィードになりやすいです。
この記事では、TwexAPI で公開 X List の投稿を取得する方法を説明します。固定件数のスナップショットが必要な場合は固定件数エンドポイントを使い、フィード、アーカイブ、定期監視を作る場合は cursor ベースのページングエンドポイントを使います。
エンドポイントを選ぶ
TwexAPI には、List Tweets を取得する実用的な方法が 2 つあります。
| 目的 | エンドポイント | 使う場面 |
|---|---|---|
| 一度だけのスナップショット | GET /twitter/list/{list_id}/tweets/{target_count} | List から固定件数の最近の投稿を取得したいとき。 |
| 再利用できるフィードやアーカイブ | POST /twitter/list/tweets/page | next_cursor でページングし、収集状態を保存したいとき。 |
どちらも Bearer Token が必要です。list_id は読み取りたい X List の数値 ID です。
固定件数のスナップショットを取得する
簡単な確認には、path パラメータで list_id と target_count を渡します。
curl --request GET \
--url https://api.twexapi.io/twitter/list/<list_id>/tweets/50 \
--header 'Authorization: Bearer <token>'成功レスポンスには code、msg、data が含まれます。data は tweet オブジェクトの配列です。
1{
2 "code": 200,
3 "msg": "success",
4 "data": [
5 {
6 "tweet_id": "1234567890123456789",
7 "created_at": "Mon Jul 01 12:34:56 +0000 2025",
8 "text": "<API が返した投稿本文>",
9 "favorite_count": 120,
10 "retweet_count": 18
11 }
12 ]
13}このエンドポイントは簡単ですが、cursor は返しません。前回の続きから取得したい場合は、ページングエンドポイントを使います。
List フィードをページングする
継続的な監視では POST /twitter/list/tweets/page を呼び出します。初回は next_cursor を空にし、次回以降は前ページで返された cursor を渡します。
curl --request POST \
--url https://api.twexapi.io/twitter/list/tweets/page \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"list_id": "<list_id>"
}'レスポンスの has_next_page が true の場合は、次ページを取得します。
curl --request POST \
--url https://api.twexapi.io/twitter/list/tweets/page \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"list_id": "<list_id>",
"next_cursor": "cursor_from_previous_response"
}'ページング中は list_id を変更しないでください。cursor は、それを生成した List と収集状態に対してのみ意味があります。
Python エクスポートスクリプト
次のスクリプトは List 投稿を JSONL に書き出し、cursor チェーンを含むメタデータファイルを作成します。後から再開や監査がしやすくなります。
1import json
2import time
3from datetime import datetime, timezone
4from pathlib import Path
5
6import requests
7
8TOKEN = "<your_bearer_token>"
9LIST_ID = "<list_id>"
10URL = "https://api.twexapi.io/twitter/list/tweets/page"
11OUT = Path(f"x-list-{LIST_ID}-tweets.jsonl")
12META = Path(f"x-list-{LIST_ID}-tweets-meta.json")
13
14headers = {
15 "Authorization": f"Bearer {TOKEN}",
16 "Content-Type": "application/json",
17}
18
19seen_ids = set()
20cursor = None
21page_log = []
22page_number = 0
23
24with OUT.open("w", encoding="utf-8") as f:
25 while True:
26 payload = {"list_id": LIST_ID}
27 if cursor:
28 payload["next_cursor"] = cursor
29
30 response = requests.post(URL, headers=headers, json=payload, timeout=30)
31 response.raise_for_status()
32 body = response.json()
33
34 page_number += 1
35 tweets = body.get("data") or []
36
37 for tweet in tweets:
38 tweet_id = tweet.get("tweet_id")
39 if not tweet_id or tweet_id in seen_ids:
40 continue
41 seen_ids.add(tweet_id)
42 f.write(json.dumps(tweet, ensure_ascii=False) + "\n")
43
44 page_log.append({
45 "page": page_number,
46 "items": len(tweets),
47 "has_next_page": body.get("has_next_page"),
48 "next_cursor": body.get("next_cursor"),
49 })
50
51 if not body.get("has_next_page") or not body.get("next_cursor"):
52 break
53
54 cursor = body["next_cursor"]
55 time.sleep(1)
56
57META.write_text(json.dumps({
58 "list_id": LIST_ID,
59 "exported_at": datetime.now(timezone.utc).isoformat(),
60 "unique_tweets": len(seen_ids),
61 "pages": page_log,
62}, ensure_ascii=False, indent=2), encoding="utf-8")
63
64print(f"Saved {len(seen_ids)} tweets to {OUT}")本番ジョブでは、各ページの取得に成功するたびに最後の cursor を保存します。途中で停止しても、最初からやり直さず、最後に成功した位置から再開できます。
List 投稿を使いやすいフィードにする
エクスポート後は、プロダクトで必要なフィールドを正規化します。
tweet_id、created_at、本文、作者フィールド、レスポンスに含まれるエンゲージメント数。https://x.com/i/web/status/<tweet_id>のような標準投稿 URL。作者情報がある場合は作者の status URL も作れます。- そのレコードを生成した
list_id、エクスポート時刻、page cursor。 - 安定した重複排除キー。通常は
tweet_idです。
List は人が管理するため、メンバーが変わることがあります。メンバー変更後のエクスポートは、以前とは異なる編集視点を反映する可能性があります。分析で一貫性が重要なら、List メタデータも別に保存してください。
実用的なユースケース
- 記者や専門家の List からニュースデスク用フィードを作る。
- 創業者、アナリスト、プロダクトアカウントの List で競合カテゴリを追跡する。
- コミュニティや市場を代表する公開 List から調査データセットを作る。
- 編集者が確認して共有する候補投稿のワークフローを作る。
- 広いキーワード検索を書かずに、狭いトピックを監視する。
List アプローチは、メンバー構成に意味があるときに最も有効です。List が古い、広すぎる、または管理者が不明な場合は、フィードを信頼する前にメンバーを確認しましょう。
よくある落とし穴
- パスを間違える。現在の List Tweets エンドポイントは単数の
listパスセグメントを使います。古い複数形の書き方は使いません。 - List を会話全体として扱う。List はキュレーションされた一部であり、トピック全体のアーカイブではありません。
- 履歴エクスポートを比較している途中で List を変更する。メンバー変更によりフィード内容が変わります。
- cursor メタデータを保存しない。保存しないと、どこまで取得したのか説明しにくくなります。
- タイムスタンプなしでエンゲージメント数を上書きする。数値は変わるため、スナップショットには収集日が必要です。
まとめ
素早く取得するなら GET /twitter/list/{list_id}/tweets/{target_count} を使います。フィードやアーカイブを作るなら POST /twitter/list/tweets/page を使い、各ページと cursor の履歴をデータセットと一緒に保存します。
この流れにすると、広いタイムラインを取得したり、ノイズの多いキーワード検索に頼ったりするよりも、きれいで説明しやすい収集ワークフローになります。