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つ以上の公開Xユーザー名を用意します。先頭の @ は任意です。
- usernames と有効な results_limit を /v1/x/followers-list に POST し、返された task_id を保存します。
- タスクが succeeded または failed になるまで /v1/tasks/{task_id} をポーリングします。
- 成功したら 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 trueX Followers List API の主なユースケース
- オーディエンス調査用サンプルの作成: 選定したXプロフィールの公開フォロワーアカウントを取得し、返されたサンプル全体で表示中のアカウント規模を分析します。
- 既知のアカウントディレクトリの補完: 後続のアカウントレコードに、正規のXプロフィールURL、表示名などの情報、アカウントID、表示中の各種カウントを追加します。
- 再現可能なフォロワーのスナップショット作成: 同じ条件の取得を定期的に実行し、タスクのタイムスタンプを保持して、保存された公開アカウントの集合を比較します。
X Followers List API 活用のヒント
- 一時的なクレジットの見積もりは送信した配列の長さに基づき、重複するハンドルは取得時に正規化されるため、送信前にユーザー名の重複を排除してください。
- results_limit はユーザー名ごとの上限であり、すべてのアカウントで指定した件数の公開レコードが返されることを保証するものではありません。
- 各結果の id を固定キーとして使用してください。複数の送信ユーザー名で同じフォロワーが見つかった場合でも、1つのタスク内では1回だけ保存されます。
- 取得元のページネーションと結果の取得は区別してください。公開されるのは /v1/tasks/{task_id} の不透明な next_cursor のみです。
- 利用できないアカウント、アクセス制限、取得元のデータ切れによって取得件数が減ることがあるため、空の結果や一部のみの結果でもワークフローが失敗しないように処理してください。
関連API
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 — あるアカウントがほかのアカウントをフォローしているか、相手がフォローバックしているかを確認します。
- Twitter Tweet Scraper API
- Twitter User Tweets Scraper API
- Twitter Search API
- X Post Quotes API
- X Post Replies API
- X Trends API
- Twitter Mentions API
- Twitter User Search API
- X Community Posts API
- X Thread Context API
- X Account Location API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Communities Search API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Video Transcript API