TwexAPI で X コミュニティ内の投稿を検索する方法

X Communities には、メインタイムラインより狭く、文脈の濃い議論が集まることがあります。コミュニティ ID が分かっていて、その中で特定のトピックに関する投稿を探したい場合は、POST https://api.twexapi.io/twitter/community/search-tweets を使います。

広い X 検索ではノイズが多すぎるとき、このエンドポイントが役立ちます。キーワードの全公開投稿を集めるのではなく、特定コミュニティ内に絞って、その場に参加している人の投稿を確認できます。

このエンドポイントでできること

POST /twitter/community/search-tweets は、1 つの X Community 内で tweets を検索します。

リクエストには 3 つの必須フィールドがあります。

フィールド	型	用途
`community_id`	string	検索対象の X Community ID。
`target_count`	integer	検索する tweet 数。クエリ調整中は小さめの値から始めます。
`query`	string	コミュニティ内で一致させるキーワードまたは検索フレーズ。

次のようなワークフローに向いています。

ニッチなコミュニティで製品、トピック、リリースがどう語られているかを確認する。
コミュニティレポートや社内ダイジェストに使う投稿を集める。
自社コミュニティ内の繰り返し質問を追跡する。
同じトピックが複数コミュニティでどう違って現れるかを比べる。

このエンドポイントが返すのはソーシャル投稿です。モデレーション方針、顧客調査、人によるレビューの代わりにはなりません。

基本リクエスト

curl --request POST \
  --url https://api.twexapi.io/twitter/community/search-tweets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "community_id": "1234567890123456789",
    "target_count": 50,
    "query": "customer support"
  }'

成功レスポンスには code、msg、data が含まれます。data の各要素は tweet オブジェクトです。よく使うフィールドは tweet_id、text、full_text、created_at、created_at_datetime、favorite_count、retweet_count、reply_count、quote_count、hashtags、cashtags、media、ユーザー情報などです。

1{
2  "code": 200,
3  "msg": "success",
4  "data": [
5    {
6      "tweet_id": "1803006263529541838",
7      "text": "Example community post about customer support",
8      "created_at_datetime": "2024-06-17T03:51:48.000Z",
9      "favorite_count": 18,
10      "retweet_count": 3,
11      "reply_count": 6,
12      "hashtags": ["support"]
13    }
14  ]
15}

Python クライアント

クライアントは小さく保ちます。返された投稿の並び替え、保存、レビュー方法は呼び出し側で決めます。

1import os
2from typing import Any
3
4import requests
5
6API_URL = "https://api.twexapi.io/twitter/community/search-tweets"
7TOKEN = os.environ["TWEXAPI_BEARER_TOKEN"]
8
9def search_community_tweets(
10    community_id: str,
11    query: str,
12    *,
13    target_count: int = 50,
14) -> list[dict[str, Any]]:
15    payload = {
16        "community_id": community_id,
17        "target_count": target_count,
18        "query": query,
19    }
20
21    response = requests.post(
22        API_URL,
23        headers={
24            "Authorization": f"Bearer {TOKEN}",
25            "Content-Type": "application/json",
26        },
27        json=payload,
28        timeout=30,
29    )
30    response.raise_for_status()
31    return response.json().get("data", [])
32
33if __name__ == "__main__":
34    tweets = search_community_tweets(
35        "1234567890123456789",
36        "customer support",
37        target_count=25,
38    )
39    for tweet in tweets[:5]:
40        text = tweet.get("full_text") or tweet.get("text") or ""
41        print(tweet.get("tweet_id"), text[:140])

レビュー用の行に整える

最初から複雑なダッシュボードを作る必要はありません。まずは各 tweet を、分析担当者やコミュニティマネージャーが確認しやすい安定した行データにします。

1def to_review_row(tweet: dict[str, Any]) -> dict[str, Any]:
2    favorite_count = tweet.get("favorite_count") or 0
3    retweet_count = tweet.get("retweet_count") or 0
4    reply_count = tweet.get("reply_count") or 0
5    quote_count = tweet.get("quote_count") or 0
6    engagement = favorite_count + retweet_count + reply_count + quote_count
7
8    return {
9        "tweet_id": tweet.get("tweet_id"),
10        "created_at": tweet.get("created_at_datetime") or tweet.get("created_at"),
11        "engagement": engagement,
12        "hashtags": ", ".join(tweet.get("hashtags") or []),
13        "text": tweet.get("full_text") or tweet.get("text") or "",
14        "url": f"https://x.com/i/status/{tweet.get('tweet_id')}",
15    }
16
17tweets = search_community_tweets(
18    "1234567890123456789",
19    "pricing",
20    target_count=100,
21)
22rows = [to_review_row(tweet) for tweet in tweets]
23rows.sort(key=lambda row: row["engagement"], reverse=True)
24
25for row in rows[:10]:
26    print(row["engagement"], row["url"], row["text"][:100])

正規化した行だけでなく、raw tweet payload も保存しておくと便利です。あとで別のフィールドが必要になっても、検索を再実行せずに確認できます。

複数コミュニティを比較する

同じ query を複数コミュニティで比較する場合は、明示的にループします。失敗をログに残しやすく、異なる受け手の結果を混ぜずに済みます。

1communities = {
2    "1234567890123456789": "Product builders",
3    "2345678901234567890": "Support leaders",
4    "3456789012345678901": "AI operators",
5}
6
7query = "onboarding"
8summary = []
9
10for community_id, name in communities.items():
11    tweets = search_community_tweets(community_id, query, target_count=50)
12    rows = [to_review_row(tweet) for tweet in tweets]
13    total_engagement = sum(row["engagement"] for row in rows)
14    summary.append(
15        {
16            "community_id": community_id,
17            "name": name,
18            "tweet_count": len(rows),
19            "total_engagement": total_engagement,
20        }
21    )
22
23for item in sorted(summary, key=lambda row: row["total_engagement"], reverse=True):
24    print(item["name"], item["tweet_count"], item["total_engagement"])

これらの数値は初期の優先順位付けに使うものです。投稿数が少ないコミュニティでも、文脈の質が高い場合があります。

監視パターン

継続的に監視する場合は、定期的に検索し、tweet_id で重複排除します。

狭い query でコミュニティを検索する。
返ってきた各投稿の tweet_id を保存する。
すでに処理済みの行はスキップする。
新しい行をエンゲージメントと投稿時刻で並べる。
優先度の高い投稿だけを人のレビューキューに送る。

コミュニティの未フィルタ feed が必要な場合、TwexAPI には GET /twitter/community/{community_id}/tweets/{tweet_type}/{target_count} やページング対応のコミュニティ投稿取得もあります。完全な feed よりキーワードが重要なときは、この search endpoint を使います。

よくある落とし穴

このエンドポイントは community_id が必要です。コミュニティ slug は渡さないでください。
query は具体的にします。単語 1 つだけだと意図が混ざりやすくなります。
target_count は取得上限として扱い、すべての結果が有用だとは考えないでください。
定期実行を始める前に、tweet_id を重複排除キーとして保存します。
レポートに使う前に投稿を確認してください。コミュニティ投稿には冗談、皮肉、脱線返信、内輪の文脈が含まれることがあります。

まとめ

POST /twitter/community/search-tweets は、1 つの X Community 内で集中して調査したいときに向いています。community_id、query、target_count を渡し、レスポンスをレビューしやすい行データに整えます。

この流れなら、投稿を集め、文脈を残し、何が重要かを人が判断できます。