x/
followers-list

1つ以上のXユーザー名について公開フォロワーアカウントを取得します。正規化されたアカウント情報と表示中のプロフィール数値を、非同期タスクとカーソル方式で取得できます。

X Followers List API

フォロワーアカウント
プロフィールの数値
一括取得
結果1件あたり0.5クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

X Followers List

Xのフォロワーリストは、取得時点で送信したユーザー名をフォローしているユーザーについて返される、公開アカウントレコードの集合です。オーディエンス調査やリストの情報補完に活用できますが、公開状況、取得元のページネーション、タスク単位の重複排除の影響を受けます。

X Followers List API の主な機能

  • 複数アカウントのフォロワー取得1つのタスクで1つ以上の公開Xユーザー名を送信できます。先頭の @ の有無は問いません。
  • ユーザー名ごとの取得件数指定ユーザー名ごとに200から2,000件のフォロワーレコードを200単位でリクエストできます。デフォルトは200です。
  • 正規化された公開アカウントレコード公開タスクの結果として、アカウントID、正規プロフィールURL、投稿者情報、表示中のプロフィールカウント、正規化されたタイムスタンプを受け取れます。
  • 非同期での結果受け取り取得が完了するまでタスク結果をポーリングし、その後は不透明なカーソルを使って利用可能なすべての結果ページを順に取得します。

X Followers List API のパラメータ

パラメータ必須説明
usernames必須必須。公開Xユーザー名のリストです。先頭の @ は付けても付けなくてもかまいません。取得前に前後の空白は除去され、大文字・小文字を区別せずに重複するユーザー名が取り除かれます。
results_limit任意ユーザー名ごとに取得する結果の最大数です。デフォルトは200で、200から2,000までの200の倍数を指定できます。

X Followers List API の使い方

フォロワー取得タスクを開始し、完了を待ってから、保存された公開アカウントレコードをページ単位で取得します。

  1. 1つ以上の公開Xユーザー名を用意します。先頭の @ は任意です。
  2. usernames と有効な results_limit を /v1/x/followers-list に POST し、返された task_id を保存します。
  3. タスクが succeeded または failed になるまで /v1/tasks/{task_id} をポーリングします。
  4. 成功したら data.results.items を読み取り、has_more が true の間は next_cursor をタスクエンドポイントに渡して続きを取得します。
curl -X POST "https://api.socq.ai/v1/x/followers-list" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["@X"],"results_limit":200}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

X Followers List API の主なユースケース

  • オーディエンス調査用サンプルの作成: 選定したXプロフィールの公開フォロワーアカウントを取得し、返されたサンプル全体で表示中のアカウント規模を分析します。
  • 既知のアカウントディレクトリの補完: 後続のアカウントレコードに、正規のXプロフィールURL、表示名などの情報、アカウントID、表示中の各種カウントを追加します。
  • 再現可能なフォロワーのスナップショット作成: 同じ条件の取得を定期的に実行し、タスクのタイムスタンプを保持して、保存された公開アカウントの集合を比較します。

X Followers List API 活用のヒント

  • 一時的なクレジットの見積もりは送信した配列の長さに基づき、重複するハンドルは取得時に正規化されるため、送信前にユーザー名の重複を排除してください。
  • results_limit はユーザー名ごとの上限であり、すべてのアカウントで指定した件数の公開レコードが返されることを保証するものではありません。
  • 各結果の id を固定キーとして使用してください。複数の送信ユーザー名で同じフォロワーが見つかった場合でも、1つのタスク内では1回だけ保存されます。
  • 取得元のページネーションと結果の取得は区別してください。公開されるのは /v1/tasks/{task_id} の不透明な next_cursor のみです。
  • 利用できないアカウント、アクセス制限、取得元のデータ切れによって取得件数が減ることがあるため、空の結果や一部のみの結果でもワークフローが失敗しないように処理してください。

X Followers List API 以外に別の種類の公開Xデータが必要な場合は、これらのAPIをご利用ください。

  • Twitter Profile Scraper API — ユーザー名から、公開アカウントの情報、プロフィール文、アバター、カバー画像、アカウントの状態、表示中のオーディエンス統計を取得します。
  • X Following List API — 公開Xアカウントがフォローしているプロフィールを、アカウント情報、プロフィール文、アカウントシグナル、表示中のカウント、元のユーザー名とともに取得します。
  • X Post Retweeters API — 既知のXまたはTwitterのステータスURLをリポストしたアカウントについて、正規化された公開プロフィールをタスク単位で重複なく取得します。
  • X Community API — コミュニティのリンクから、説明、メンバー数、ルール、参加ポリシーを取得します。
  • X Verified Followers API — プロフィールをフォローしている認証済みアカウントを、ユーザー名、表示名、アイコン、登録日とともに取得します。
  • Twitter Follow Checker API — あるアカウントがほかのアカウントをフォローしているか、相手がフォローバックしているかを確認します。

他のプラットフォームを見る

Xのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

X Followers List API — よくある質問

X Followers List APIは、送信した1つ以上のXユーザー名をフォローしているユーザーについて、公開アカウントレコードを取得するためのプログラムインターフェースです。

空でない usernames 配列を渡してください。各値の先頭に @ を付けても付けなくてもかまいません。取得元での取得前に前後の空白は除去され、大文字・小文字を区別せずに重複するハンドルが取り除かれます。

この値はユーザー名ごとに個別に適用されます。デフォルトは200で、200から2,000までの200の倍数を指定する必要があります。これは上限値のため、公開状況やページネーションによって結果が少なくなることがあります。

現在のタスクシリアライザーは、アカウントID、正規プロフィールURL、投稿者ID、ユーザー名と名前、表示中のプロフィール数値、取得可能な場合は正規化されたアカウント作成日時、保存レコードの作成日時を返します。

取得元で繰り返し返された行はアカウントIDで重複排除され、同じアカウントが複数の送信ユーザー名をフォローしている場合でも、タスク全体で1回だけ保存されます。

一意に保存された結果1件につき0.5 SocQクレジットです。タスクでは results_limit に送信したユーザー名の数を掛けた分が事前に引き当てられ、精算が正常に完了した後に未使用分のクレジットが返金されます。結果が空の場合は0クレジットです。