> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# フォロワーとフォロー中ユーザー

# APIでTwitterのフォロワー・フォロー中ユーザー一覧を取得する

公開X（旧Twitter）アカウントのフォロワー一覧とフォロー中ユーザー一覧は、価値の高いデータです。フォロワー一覧は、ブランド、話題、人物に誰が関心を持っているかを示します。フォロー中の一覧は、そのアカウントが注目する相手、影響を受ける人、競合、情報源を示します。両方を使うと、アカウント周辺のつながりを把握できます。

Sorsa APIには、`/followers`（アカウントをフォローしている人）と`/follows`（アカウントがフォローしている人）があります。いずれも1リクエストで最大200件の完全なプロフィールを返し、カーソルによるページネーションで全一覧を取得できます。各ユーザーには自己紹介、フォロワー数、ツイート数、所在地、認証状態、プロフィール画像などが含まれます。

このガイドでは、最小限のリクエストから、フィルタリング、オーディエンスの重複分析、ページネーションを組み合わせた大規模な取得まで説明します。

> **無料で開始：** `/followers`、`/follows`、`/verified-followers`を含む全エンドポイントを、最初の無料リクエスト100件で利用できます。付与は1回限りで、カード登録不要、有効期限なしです。1回で最大200プロフィールを取得できるため、有料プランに移る前に約20,000人まで取得できます。

> **注：** 追加の取得方法とオーディエンス分析の実例は、ブログの[Twitter Followers API：フォロワーとフォロー中ユーザーの取得](https://api.sorsa.io/blog/twitter-followers-api)を参照してください。

***

## 最小限の例：フォロワーを取得する

公開アカウントの最初のページを取得するには、次の1リクエストだけで十分です。

### cURL

```bash theme={null}
curl "https://api.sorsa.io/v3/followers?username=stripe" \
  -H "ApiKey: YOUR_API_KEY"
```

### Python

```python theme={null}
import requests

resp = requests.get(
    "https://api.sorsa.io/v3/followers",
    headers={"ApiKey": "YOUR_API_KEY"},
    params={"username": "stripe"},
)
for user in resp.json().get("users", []):
    print(f"@{user['username']} - {user.get('description', '')[:80]}")
```

### JavaScript

```javascript theme={null}
const resp = await fetch(
  "https://api.sorsa.io/v3/followers?username=stripe",
  { headers: { "ApiKey": "YOUR_API_KEY" } }
);
const { users } = await resp.json();
users.forEach((u) =>
  console.log(`@${u.username} - ${u.description?.slice(0, 80) ?? ""}`)
);
```

APIキーとユーザー名を指定したGETリクエストです。レスポンスには最大200プロフィールの`users`配列と、ページネーション用の`next_cursor`が含まれます。

> **ヒント：** [Recent Followers](https://api.sorsa.io/playground/recent-followers)または[API Playground](https://api.sorsa.io/playground)を使うと、コードを書かずに任意のアカウントのフォロワーを確認できます。

***

## 最小限の例：フォロー中ユーザーを取得する

`/follows`も同じ仕組みですが、対象ユーザーがフォローしているアカウントを返します。

```bash theme={null}
curl "https://api.sorsa.io/v3/follows?username=stripe" \
  -H "ApiKey: YOUR_API_KEY"
```

```python theme={null}
resp = requests.get(
    "https://api.sorsa.io/v3/follows",
    headers={"ApiKey": "YOUR_API_KEY"},
    params={"username": "stripe"},
)
for user in resp.json().get("users", []):
    print(f"@{user['username']} ({user['followers_count']} followers)")
```

***

## エンドポイントの仕様

どちらもGETで、同じ入力オプションを使います。

### `GET /v3/followers`

指定アカウントを**フォローしている**ユーザーを返します。

### `GET /v3/follows`

指定ユーザーが**フォローしている**アカウントを返します。

### 入力パラメーター（クエリ文字列）

| パラメーター        | 型       | 必須      | 説明                                          |
| :------------ | :------ | :------ | :------------------------------------------ |
| `username`    | string  | 3つのうち1つ | `@`なしのユーザー名。例：`stripe`。                     |
| `user_id`     | string  | 3つのうち1つ | 数値のユーザーID。例：`44196397`。                     |
| `user_link`   | string  | 3つのうち1つ | 完全なプロフィールURL。例：`https://x.com/stripe`。      |
| `next_cursor` | integer | いいえ     | 前のレスポンスの`next_cursor`をそのまま渡すと、次のページを取得できます。 |

`username`、`user_id`、`user_link`のいずれか1つだけを指定してください。

### レスポンス

```json theme={null}
{
  "users": [
    {
      "id": "1234567890",
      "username": "developer_jane",
      "display_name": "Jane Chen",
      "description": "Full-stack developer. Building things with APIs.",
      "location": "San Francisco, CA",
      "profile_image_url": "https://pbs.twimg.com/profile_images/...",
      "profile_background_image_url": "https://pbs.twimg.com/profile_banners/...",
      "followers_count": 4820,
      "followings_count": 312,
      "tweets_count": 1847,
      "favourites_count": 5231,
      "media_count": 89,
      "verified": false,
      "protected": false,
      "can_dm": true,
      "possibly_sensitive": false,
      "created_at": "2018-01-15T08:22:41Z",
      "bio_urls": ["https://janechen.dev"],
      "pinned_tweet_ids": ["1987654321098765432"]
    }
  ],
  "next_cursor": 1234567890
}
```

各ユーザーには次のフィールドが含まれます：`id`、`username`、`display_name`、`description`、`location`、`created_at`、`followers_count`、`followings_count`、`favourites_count`、`tweets_count`、`media_count`、`profile_image_url`、`profile_background_image_url`、`bio_urls`、`pinned_tweet_ids`、`verified`、`can_dm`、`protected`、`possibly_sensitive`。

1ページには最大**200件のユーザーオブジェクト**が含まれます。`next_cursor`があれば続きがあるので、次のリクエストの同名パラメーターに渡します。存在しないかnullなら、一覧の終端です。

***

## フォロワー一覧全体を順に取得する

1リクエストは1ページです。全フォロワーを集めるには、`next_cursor`がなくなるまで繰り返します。

### Python

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"

def get_all_followers(username, max_pages=50):
    """Fetch the complete follower list of a public account."""
    all_users = []
    cursor = None

    for page in range(max_pages):
        params = {"username": username}
        if cursor:
            params["next_cursor"] = cursor

        resp = requests.get(
            "https://api.sorsa.io/v3/followers",
            headers={"ApiKey": API_KEY},
            params=params,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()

        users = data.get("users", [])
        all_users.extend(users)
        print(f"Page {page + 1}: {len(users)} followers (total: {len(all_users)})")

        cursor = data.get("next_cursor")
        if not cursor:
            print("Reached end of list.")
            break
        time.sleep(0.05)  # stay under 20 req/s

    return all_users


followers = get_all_followers("stripe", max_pages=100)
print(f"\nTotal followers collected: {len(followers)}")
```

### JavaScript

```javascript theme={null}
const API_KEY = "YOUR_API_KEY";

async function getAllFollowers(username, maxPages = 50) {
  const allUsers = [];
  let cursor = null;

  for (let page = 0; page < maxPages; page++) {
    const params = new URLSearchParams({ username });
    if (cursor) params.set("next_cursor", cursor);

    const resp = await fetch(
      `https://api.sorsa.io/v3/followers?${params}`,
      { headers: { "ApiKey": API_KEY } }
    );
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);

    const data = await resp.json();
    allUsers.push(...(data.users || []));

    console.log(`Page ${page + 1}: ${data.users?.length || 0} followers (total: ${allUsers.length})`);

    cursor = data.next_cursor;
    if (!cursor) break;
    await new Promise((r) => setTimeout(r, 50));
  }
  return allUsers;
}

const followers = await getAllFollowers("stripe");
```

URLを変えるだけで、`/follows`にも同じ処理を使えます。

全エンドポイントに共通する挙動の詳細は、[ページネーション](https://docs.sorsa.io/ja/pagination)を参照してください。

***

## フォロー中ユーザー一覧全体を取得する

エンドポイントを差し替えるだけでコードは同じです。フォロー先を見るほうが、フォロワーを見るより多くの情報を得られることもあります。創業者のフォロー先は注目する投資家、パートナー、競合を示し、インフルエンサーのフォロー先は情報源を示します。

```python theme={null}
def get_all_following(username, max_pages=50):
    """Fetch the complete list of accounts a user follows."""
    all_users = []
    cursor = None

    for page in range(max_pages):
        params = {"username": username}
        if cursor:
            params["next_cursor"] = cursor

        resp = requests.get(
            "https://api.sorsa.io/v3/follows",
            headers={"ApiKey": API_KEY},
            params=params,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()

        users = data.get("users", [])
        all_users.extend(users)

        cursor = data.get("next_cursor")
        if not cursor:
            break
        time.sleep(0.05)

    return all_users


following = get_all_following("naval", max_pages=20)
print(f"@naval follows {len(following)} accounts")

# Sort by follower count to see the biggest names
following.sort(key=lambda u: u.get("followers_count", 0), reverse=True)
for u in following[:10]:
    print(f"  @{u['username']} ({u['followers_count']:,} followers)")
```

***

## 実践的な活用

### プロフィールの条件でフォロワーを絞り込む

そのままの一覧も有用ですが、条件で絞ると具体的な行動につなげられます。各ユーザーには完全なプロフィール情報があるため、追加のAPI呼び出しなしに任意の属性で分類できます。

```python theme={null}
followers = get_all_followers("competitor_handle", max_pages=20)

# High-value accounts: 1K+ followers, active (100+ tweets), not protected
qualified = [
    u for u in followers
    if u.get("followers_count", 0) >= 1000
    and u.get("tweets_count", 0) >= 100
    and not u.get("protected", False)
]
print(f"Qualified leads: {len(qualified)} out of {len(followers)} total")

# Accounts with websites in their bio (potential business leads)
with_websites = [u for u in followers if u.get("bio_urls")]
print(f"Accounts with website links: {len(with_websites)}")

# Filter by location keyword (self-reported)
in_usa = [
    u for u in followers
    if "usa" in (u.get("location") or "").lower()
    or "united states" in (u.get("location") or "").lower()
    or ", us" in (u.get("location") or "").lower()
]
print(f"US-based followers: {len(in_usa)}")
```

`location`はユーザーが自由入力した文章です。より信頼性の高い国単位の情報には、`/about`で各アカウントの国タグを調べてください。全体の手順は[オーディエンスの地域分布](https://docs.sorsa.io/ja/Audience-Geography)にあります。

### 競合間で重複するオーディエンスを見つける

複数の競合のフォロワーを取得し、2つ以上をフォローするユーザーを探します。同じ分野を複数回、自らフォローしているため、市場への関心が高い層と考えられます。

```python theme={null}
from collections import Counter

competitors = ["competitor1", "competitor2", "competitor3"]
all_ids = []

for handle in competitors:
    followers = get_all_followers(handle, max_pages=10)
    ids = [u["id"] for u in followers]
    all_ids.extend(ids)
    print(f"@{handle}: {len(followers)} followers collected")

# Count how many competitor lists each user appears in
counts = Counter(all_ids)
overlap = {uid: count for uid, count in counts.items() if count >= 2}
print(f"\nUsers following 2+ competitors: {len(overlap)}")
```

自己紹介検索やコミュニティ調査も組み合わせる方法は、[ターゲット層の発見](https://docs.sorsa.io/ja/target-audiences-Discovery)を参照してください。

### 業界の主要人物がフォローする相手を見つける

専門家やオピニオンリーダーのフォロー先を取得して、誰に注目しているかを調べます。専門分野のアカウント、新しい発信者、主要人物が頼るツールなどを発見できます。

```python theme={null}
following = get_all_following("pmarca", max_pages=10)

print(f"@pmarca follows {len(following)} accounts. Top by follower count:")
following.sort(key=lambda u: u.get("followers_count", 0), reverse=True)
for u in following[:15]:
    print(f"  @{u['username']} ({u['followers_count']:,} followers)")
    print(f"    {u.get('description', '')[:70]}\n")
```

***

## 認証済みフォロワー

`/verified-followers`は`/followers`と同じように使えますが、認証済みアカウント（青・金・灰色のチェックマーク）だけを返します。次の2つの場面で役立ちます。

1. 全一覧を後処理せず、**注目度の高いアカウントに絞り込む**。
2. 認証済みユーザーが少数の**大規模アカウントで無駄なリクエストを減らす**。フォロワー1,000万人から認証済み5,000人を見つけるために全一覧を読むと50,000リクエストですが、`/verified-followers`なら約25リクエストです。

```bash theme={null}
curl "https://api.sorsa.io/v3/verified-followers?username=stripe" \
  -H "ApiKey: YOUR_API_KEY"
```

レスポンス構造とページネーションは`/followers`と同じです。`next_cursor`で同様に繰り返します。詳細は[APIリファレンス](https://docs.sorsa.io/ja/api-reference/users-data/verified-followers)を参照してください。

***

## 大規模取得の利用量を見積もる

1ページは最大200件です。計画時の目安は次のとおりです。

| アカウントの規模        | 必要ページ数 | リクエスト数 |
| :-------------- | :----- | :----- |
| フォロワー1,000人     | 5      | 5      |
| フォロワー10,000人    | 50     | 50     |
| フォロワー100,000人   | 500    | 500    |
| フォロワー1,000,000人 | 5,000  | 5,000  |

毎秒20リクエストなら、50回と500回のレート制限上の理論的な最短時間は2.5秒と25秒です。ただし、1本のカーソル処理は順次実行され、各ページが前のレスポンスに依存します。実際には通信待ち、送信間隔、再試行の時間もかかります。数百万フォロワーのアカウントでは、全件が必要な場合を除き、最初の50ページ（約10,000人）などのサンプリングを検討してください。

1回で最大200プロフィールを取得するため、消費リクエスト数は少なく済みます。無料の100リクエストで約20,000人、Starter（月間10,000リクエスト）で約2,000,000人、Pro（月間100,000リクエスト）で約20,000,000人を取得できます。全料金は[料金ページ](https://api.sorsa.io/pricing)を参照してください。

***

## データの鮮度と注意点

**フォロワーの順序。** `/followers`はXが返す順序で並び、一般的には新しくフォローした人が先です。最初のページには最近獲得したフォロワーが含まれます。

**非公開アカウント。** 対象が保護された非公開アカウントの場合、フォロワー・フォロー中一覧にはアクセスできず、エラーになります。

**フォロワー数と取得一覧の違い。** `followers_count`はXが管理するリアルタイムの件数です。凍結、無効化、最近削除されたアカウントにより、取得可能な一覧とは少し異なることがあります。大規模なアカウントでは数%の差を見込み、`followers_count`との厳密な一致を検証しないでください。これはSorsa固有ではなく、プラットフォーム側の挙動です。

**プロフィールは現在の情報です。** 各オブジェクトはフォローした時点ではなく、リクエスト時点の自己紹介、フォロワー数、ユーザー名を返します。数値の`id`は固定ですが、ユーザー名は変わり得ます。

**非常に大きいアカウントのサンプリング。** 約500,000人を超える場合、最初の50〜100ページ（最大10,000〜20,000人）は最近のフォロワーの調査に役立ちます。ただし順序に偏りがあり、全体を代表する無作為標本ではありません。完全な網羅が必要な理由がなければ、全件取得が必要な場面は多くありません。

***

## 次のステップ

* [ターゲット層の発見](https://docs.sorsa.io/ja/target-audiences-Discovery)：フォロワー取得、自己紹介検索、コミュニティ調査、投稿分析を組み合わせる。
* [競合分析](https://docs.sorsa.io/ja/Competitor-Analysis)：競合調査のパイプラインにフォロワーとフォロー先の情報を組み込む。
* [オーディエンスの地域分布](https://docs.sorsa.io/ja/Audience-Geography)：`/about`でフォロワーの国別分布を調べる。
* [ページネーション](https://docs.sorsa.io/ja/pagination)：大規模取得の共通パターン。
* [APIリファレンス](https://docs.sorsa.io/ja/api-reference-guide)：`/followers`、`/follows`、`/verified-followers`を含む全エンドポイントの仕様。