> ## 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.

# Seguidores e contas seguidas

# Como consultar seguidores e contas seguidas pela API

Seguidores mostram quem se interessa por uma marca, assunto ou pessoa. Contas seguidas mostram a quem essa pessoa presta atenção: referências, concorrentes e fontes de informação. Juntas, as listas ajudam a mapear a rede social de uma conta pública do X.

`/followers` retorna quem segue uma conta; `/follows` retorna quem ela segue. Ambos oferecem até 200 perfis completos por chamada, com paginação por cursor. Os perfis incluem bio, contadores, localização, verificação, imagens e mais. Este guia vai da primeira chamada à extração com filtros e análise de sobreposição.

> **Comece grátis:** as primeiras 100 requisições funcionam em todos os endpoints, incluindo `/followers`, `/follows` e `/verified-followers`, sem cartão e sem validade. Com páginas completas, isso cobre aproximadamente 20.000 seguidores.

> Veja outros métodos e exemplos de análise no [guia de seguidores do blog](https://api.sorsa.io/blog/twitter-followers-api).

## Exemplo simples: obter seguidores

Uma chamada obtém a primeira página de seguidores de uma conta pública.

### 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) ?? ""}`)
);
```

A requisição GET leva sua chave e um nome de usuário. A resposta contém `users` com até 200 perfis e `next_cursor`.

> Teste sem código com [Recent Followers](https://api.sorsa.io/playground/recent-followers) ou [API Playground](https://api.sorsa.io/playground).

## Exemplo simples: obter contas seguidas

`/follows` funciona da mesma forma, retornando as contas que o usuário segue:

```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)")
```

## Referência dos endpoints

### GET /v3/followers

Retorna os usuários que **seguem** a conta indicada.

### GET /v3/follows

Retorna as contas que o usuário indicado **segue**.

### Parâmetros de consulta

| Parâmetro     | Tipo    | Obrigatório | Descrição                                                               |
| :------------ | :------ | :---------- | :---------------------------------------------------------------------- |
| `username`    | string  | Um dos três | Nome sem @, como `stripe`.                                              |
| `user_id`     | string  | Um dos três | ID numérico, como `44196397`.                                           |
| `user_link`   | string  | Um dos três | URL completa, como `https://x.com/stripe`.                              |
| `next_cursor` | integer | Não         | Use o valor retornado na resposta anterior para obter a próxima página. |

Envie exatamente um entre `username`, `user_id` e `user_link`.

### Resposta

```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
}
```

Cada perfil inclui `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` e `possibly_sensitive`.

Cada página contém até **200 usuários**. Continue com `next_cursor` até ele ficar ausente ou nulo.

## Percorrer a lista completa de seguidores

Repita as chamadas usando o 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");
```

Para `/follows`, troque apenas a URL. Veja o comportamento geral em [paginação](https://docs.sorsa.io/pt-BR/pagination).

## Obter a lista completa de contas seguidas

O código é o mesmo com outro endpoint. As contas seguidas por fundadores podem revelar investidores, parceiros e concorrentes; as seguidas por influenciadores mostram suas fontes.

```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)")
```

## Aplicações práticas

### Filtrar por critérios do perfil

Como os perfis vêm completos, você pode segmentar a audiência sem chamadas extras:

```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` é texto livre informado pelo usuário. Para dados de país mais confiáveis, use `/about`. Veja [localização da audiência](https://docs.sorsa.io/pt-BR/Audience-Geography).

### Encontrar sobreposição entre concorrentes

Compare listas e encontre pessoas que seguem dois ou mais concorrentes. Isso sinaliza interesse recorrente no tema.

```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)}")
```

Combine seguidores, busca em bios e comunidades no guia de [descoberta do público-alvo](https://docs.sorsa.io/pt-BR/target-audiences-Discovery).

### Descobrir quem os especialistas seguem

As contas seguidas por líderes do setor podem revelar perfis de nicho, novas vozes e ferramentas relevantes.

```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")
```

## Seguidores verificados

`/verified-followers` funciona como `/followers`, mas retorna apenas contas com selo azul, dourado ou cinza. Use para filtrar perfis verificados sem processar a lista inteira e reduzir chamadas quando eles são minoria.

Em uma conta com 10 milhões de seguidores e 5.000 verificados, percorrer tudo exige cerca de 50.000 chamadas; consultar apenas verificados exige aproximadamente 25.

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

A estrutura e a paginação são iguais às de `/followers`. Veja a [referência](https://docs.sorsa.io/pt-br/api-reference/usu%C3%A1rios/seguidores-verificados).

## Estimar o consumo

| Tamanho da conta     | Páginas | Requisições |
| :------------------- | :------ | :---------- |
| 1.000 seguidores     | 5       | 5           |
| 10.000 seguidores    | 50      | 50          |
| 100.000 seguidores   | 500     | 500         |
| 1.000.000 seguidores | 5.000   | 5.000       |

A 20 req/s, os limites inferiores teóricos para 50 e 500 chamadas são 2,5 e 25 segundos. Porém, uma cadeia de cursores é sequencial: cada página depende da anterior. O tempo real inclui latência, pausas e novas tentativas. Para milhões de seguidores, considere uma amostra, como 50 páginas (cerca de 10.000 perfis), se não precisar de cobertura completa.

Com páginas de 200, as 100 chamadas gratuitas cobrem cerca de 20.000 perfis; Starter (10.000 chamadas/mês), cerca de 2 milhões; Pro (100.000/mês), cerca de 20 milhões. Veja [preços](https://api.sorsa.io/pricing).

## Atualização dos dados e casos especiais

**Ordem dos seguidores.** A ordem é fornecida pelo X e costuma ser cronológica inversa, com seguidores recentes primeiro.

**Contas protegidas.** As listas não estão acessíveis; o endpoint retorna erro.

**Contador e lista extraída.** `followers_count` é um contador do X. A lista pode divergir por contas suspensas, desativadas ou removidas recentemente. Em contas grandes, diferenças de alguns pontos percentuais são possíveis. Não exija igualdade exata.

**Perfis atuais.** Bio, contadores e nome correspondem ao momento da consulta, não ao início da relação. O ID é estável; o nome pode mudar.

**Amostragem.** Acima de aproximadamente 500.000 seguidores, as primeiras 50–100 páginas (até 10.000–20.000 perfis) ajudam a estudar seguidores recentes. É uma amostra ordenada, não aleatória nem representativa de toda a audiência.

## Próximos passos

* [Público-alvo](https://docs.sorsa.io/pt-BR/target-audiences-Discovery): combine seguidores, bios, comunidades e conteúdo.
* [Concorrentes](https://docs.sorsa.io/pt-BR/Competitor-Analysis): inteligência competitiva.
* [Localização](https://docs.sorsa.io/pt-BR/Audience-Geography): distribuição por país.
* [Paginação](https://docs.sorsa.io/pt-BR/pagination): padrões para grandes listas.
* [Referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide): especificação completa.