Consulta de perfis do Twitter em lote por API

#Como funciona uma consulta de perfis do Twitter em lote

Uma consulta de perfis em lote envia uma lista de contas em uma requisição e recebe de volta um registro de perfil para cada conta que existe. A lista pode conter nomes de usuário ou IDs numéricos de usuário, até 100 de qualquer um por chamada. Todo registro traz os mesmos campos: o ID da conta, o nome de exibição, a bio, a localização, a data de entrada, as contagens de seguidores e de contas seguidas, a contagem de posts e os indicadores de verificação.

Para uma ou duas contas, não é preciso código: Comparar contas do Twitter mostra dois perfis lado a lado, de graça. Uma lista de centenas ou milhões de contas pede uma API. O trabalho é o mesmo em qualquer lugar: dividir a lista em blocos de 100, chamar o endpoint em lote uma vez por bloco e gravar as linhas em um arquivo ou em um banco de dados.

A API oficial do X chama esses endpoints de consulta de usuários (abre em uma nova aba). O GET /2/users aceita até 100 IDs de usuário e o GET /2/users/by até 100 nomes de usuário, e os campos além de ID, nome e nome de usuário precisam ser pedidos em user.fields. A página de preços (abre em uma nova aba) do X cobra User: Read a US$ 0,010 por perfil devolvido, US$ 10,00 por 1.000, cobrando a mesma conta uma vez por dia UTC. As chamadas exigem uma conta de desenvolvedor e um bearer token, e os limites de taxa (abre em uma nova aba) permitem 300 requisições de consulta por 15 minutos por app: no máximo 30 mil perfis a cada 15 minutos.

Contas que não existem mais não são erros. Um nome de usuário digitado errado, renomeado, suspenso ou apagado simplesmente não tem registro na resposta, então um trabalho de consulta sempre compara o que voltou com o que foi enviado.

#Consulte perfis em lote com a Sorsa API

A Sorsa API, uma API e scraper do Twitter (X) para dados públicos, faz a consulta inteira com um único endpoint: o GET /info-batch (abre em uma nova aba) aceita até 100 nomes de usuário ou 100 IDs de usuário por requisição e devolve cada perfil com todos os campos, sem nada para ativar. Para consultar milhares de perfis do X de uma vez, use a Sorsa API: 100 perfis por requisição, 20 requisições por segundo em todos os planos, a partir de US$ 0,014 por 1.000 perfis.

1. Pegue uma chave. Cadastre-se e copie a chave de API do seu painel. A conta começa com 100 requisições grátis, sem precisar de cartão, e a Sorsa API nunca pede seu login do X.

2. Envie até 100 nomes de usuário. Repita o parâmetro usernames uma vez para cada conta, sem o @.

   curl -G "https://api.sorsa.io/v3/info-batch" \
     -H "ApiKey: YOUR_API_KEY" \
     --data-urlencode "usernames=harborline_analytics" \
     --data-urlencode "usernames=quietfield_records" \
     --data-urlencode "usernames=deleted_account_2019"
   

   {
     "users": [
       {
         "id": "1427632236659332516",
         "username": "harborline_analytics",
         "display_name": "Harborline Analytics",
         "description": "Port and shipping data, charted weekly.",
         "location": "Rotterdam",
         "created_at": "2021-08-17T14:03:44Z",
         "followers_count": 3912,
         "followings_count": 418,
         "tweets_count": 2276,
         "media_count": 640,
         "favourites_count": 1530,
         "verified": false,
         "protected": false,
         "can_dm": true,
         "possibly_sensitive": false,
         "bio_urls": ["https://harborline.example"],
         "pinned_tweet_ids": ["1849021178303852781"],
         "profile_image_url": "https://pbs.twimg.com/profile_images/1427/hl.jpg",
         "profile_background_image_url": "https://pbs.twimg.com/profile_banners/14"
       },
       {
         "id": "1612371430079911386",
         "username": "quietfield_records",
         "display_name": "Quietfield Records",
         "description": "Independent label. Vinyl, tapes, late nights.",
         "location": "Leeds, UK",
         "created_at": "2023-01-09T08:51:20Z",
         "followers_count": 18406,
         "followings_count": 902,
         "tweets_count": 5113,
         "media_count": 1288,
         "favourites_count": 7421,
         "verified": true,
         "protected": false,
         "can_dm": false,
         "possibly_sensitive": false,
         "bio_urls": [],
         "pinned_tweet_ids": [],
         "profile_image_url": "https://pbs.twimg.com/profile_images/1612/qf.jpg",
         "profile_background_image_url": ""
       }
     ]
   }
   

   Ver resposta completa

3. Associe por nome de usuário ou ID, nunca por posição. Entraram três nomes e saíram dois perfis: deleted_account_2019 não tem conta pública, então fica de fora de users. Compare os nomes de usuário em minúsculas, porque o X trata Harborline_Analytics e harborline_analytics como a mesma conta.

4. Envie IDs quando já os tiver. O mesmo endpoint aceita user_ids, até 100 por requisição. Os IDs sobrevivem a mudanças de nome, então uma lista que você consulta de novo e de novo funciona melhor por ID.

   import requests
   
   URL = "https://api.sorsa.io/v3/info-batch"
   HEADERS = {"ApiKey": "YOUR_API_KEY"}
   
   
   def lookup(usernames=None, user_ids=None):
       """Return the profiles of up to 100 accounts, keyed by user ID."""
       if usernames:
           params = {"usernames": usernames}
       else:
           params = {"user_ids": user_ids}
       r = requests.get(URL, headers=HEADERS, params=params, timeout=30)
       r.raise_for_status()
       return {u["id"]: u for u in r.json().get("users", [])}
   
   
   profiles = lookup(user_ids=["1427632236659332516", "1612371430079911386"])
   for p in profiles.values():
       print(p["username"], p["followers_count"], p["created_at"][:10])
   

   const URL = "https://api.sorsa.io/v3/info-batch";
   
   // Return the profiles of up to 100 accounts, keyed by user ID.
   async function lookup({ usernames = [], userIds = [] }) {
     const params = new URLSearchParams();
     usernames.forEach((u) => params.append("usernames", u));
     userIds.forEach((id) => params.append("user_ids", id));
     const res = await fetch(`${URL}?${params}`, {
       headers: { ApiKey: "YOUR_API_KEY" },
     });
     if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
     const { users = [] } = await res.json();
     return Object.fromEntries(users.map((u) => [u.id, u]));
   }
   
   const profiles = await lookup({ usernames: ["harborline_analytics"] });
   console.log(Object.values(profiles).map((p) => p.followers_count));
   

Um 401 significa que a chave está errada, um 403 que ela está ausente ou sem requisições, e um 429 que mais de 20 requisições saíram em um segundo; espere um segundo e envie o bloco de novo. Requisições com falha nunca são cobradas. Para uma única conta, o GET /info (abre em uma nova aba) devolve o mesmo registro por nome de usuário, ID de usuário ou link do perfil, mas para duas ou mais contas a chamada em lote custa a mesma única requisição.

#O que cada registro de perfil contém

Todo perfil do GET /info-batch traz 19 campos, e todos os campos voltam em todas as chamadas. A tabela os lista com o nome que a API oficial do X usa para o mesmo valor, o que ajuda quando você migra código de uma API para a outra. O X coloca as cinco contagens dentro de um objeto public_metrics, devolve a maior parte dos campos só quando user.fields os pede, e agora chama a contagem de posts de post_count e o post fixado de pinned_post_id.

• id

  Campo da API oficial do X

  id

  O que guarda

  O ID permanente do usuário, como string

• username

  Campo da API oficial do X

  username

  O que guarda

  O handle de hoje, sem o @

• display_name

  Campo da API oficial do X

  name

  O que guarda

  O nome mostrado no perfil

• description

  Campo da API oficial do X

  description

  O que guarda

  O texto da bio

• location

  Campo da API oficial do X

  location

  O que guarda

  A localização digitada no perfil

• created_at

  Campo da API oficial do X

  created_at

  O que guarda

  A data de entrada, ISO 8601

• followers_count

  Campo da API oficial do X

  followers_count (em public_metrics)

  O que guarda

  Seguidores hoje

• followings_count

  Campo da API oficial do X

  following_count (em public_metrics)

  O que guarda

  Contas que ela segue

• tweets_count

  Campo da API oficial do X

  post_count (em public_metrics)

  O que guarda

  Posts, respostas e reposts no total

• media_count

  Campo da API oficial do X

  media_count (em public_metrics)

  O que guarda

  Fotos e vídeos publicados

• favourites_count

  Campo da API oficial do X

  like_count (em public_metrics)

  O que guarda

  Posts que a conta curtiu

• verified

  Campo da API oficial do X

  verified

  O que guarda

  Se a conta tem selo de verificação

• protected

  Campo da API oficial do X

  protected

  O que guarda

  Se os posts dela são privados

• can_dm

  Campo da API oficial do X

  receives_your_dm

  O que guarda

  Se ela aceita mensagens diretas

• possibly_sensitive

  Campo da API oficial do X

  nenhum

  O que guarda

  Se o X marca a conta como sensível

• bio_urls

  Campo da API oficial do X

  url, entities

  O que guarda

  Links na bio e no perfil

• pinned_tweet_ids

  Campo da API oficial do X

  pinned_post_id

  O que guarda

  Os IDs dos posts fixados

• profile_image_url

  Campo da API oficial do X

  profile_image_url

  O que guarda

  A imagem do avatar

• profile_background_image_url

  Campo da API oficial do X

  profile_banner_url

  O que guarda

  A imagem do banner do cabeçalho

Duas coisas nunca vêm em um registro de perfil: um endereço de e-mail ou número de telefone, que o X mantém privados, e os posts da conta. O país que o X mostra em "Sobre esta conta" e o número de mudanças de nome de usuário vêm do GET /about (abre em uma nova aba), uma requisição por conta; o guia sobre o que significa "Conta baseada em" no X explica o quanto esse país é confiável.

#Enriqueça um CSV de contas com dados de perfil

O script abaixo transforma uma coluna de contas de uma planilha em uma tabela completa de perfis. Ele lê accounts.csv, cuja coluna account pode misturar nomes de usuário com ou sem @, links de perfil e IDs numéricos. Grava profiles.csv com os 19 campos mais o horário da consulta, e missing.csv com toda conta que voltou vazia.

# pip install httpx
import asyncio
import csv
from datetime import datetime, timezone

import httpx

URL = "https://api.sorsa.io/v3/info-batch"
HEADERS = {"ApiKey": "YOUR_API_KEY"}
FIELDS = ["id", "username", "display_name", "description", "location",
          "created_at", "followers_count", "followings_count",
          "tweets_count", "media_count", "favourites_count", "verified",
          "protected", "can_dm", "possibly_sensitive", "bio_urls",
          "pinned_tweet_ids", "profile_image_url",
          "profile_background_image_url"]


def normalize(cell):
    """Turn a username, @name, link or ID into (parameter, value)."""
    value = cell.split("?")[0].strip().rstrip("/").rsplit("/", 1)[-1]
    value = value.lstrip("@")
    if value.isdigit():
        return "user_ids", value
    return "usernames", value.lower()


async def fetch(client, kind, chunk):
    for attempt in range(3):
        r = await client.get(URL, params={kind: chunk})
        if r.status_code == 429:          # over 20 requests a second
            await asyncio.sleep(1 + attempt)
            continue
        r.raise_for_status()
        return r.json().get("users", [])
    r.raise_for_status()


async def run(batches):
    async with httpx.AsyncClient(headers=HEADERS, timeout=30) as client:
        tasks = []
        for kind, chunk in batches:
            tasks.append(asyncio.create_task(fetch(client, kind, chunk)))
            await asyncio.sleep(1 / 20)   # 20 requests per second
        return await asyncio.gather(*tasks)


with open("accounts.csv", newline="", encoding="utf-8") as f:
    cells = [row["account"] for row in csv.DictReader(f)
             if row["account"].strip()]

wanted = {"usernames": [], "user_ids": []}
for kind, value in dict.fromkeys(map(normalize, cells)):
    wanted[kind].append(value)
batches = [(kind, values[i:i + 100])
           for kind, values in wanted.items()
           for i in range(0, len(values), 100)]

stamp = datetime.now(timezone.utc).isoformat(timespec="seconds")
found, rows = set(), 0
with open("profiles.csv", "w", newline="", encoding="utf-8") as f:
    out = csv.DictWriter(f, fieldnames=FIELDS + ["fetched_at"])
    out.writeheader()
    for users in asyncio.run(run(batches)):
        for u in users:
            found.update({u["id"], u["username"].lower()})
            row = {k: u.get(k) for k in FIELDS}
            for k in ("bio_urls", "pinned_tweet_ids"):   # lists to text
                row[k] = " ".join(u.get(k) or [])
            row["fetched_at"] = stamp
            out.writerow(row)
            rows += 1

missing = [v for values in wanted.values() for v in values
           if v not in found]
with open("missing.csv", "w", newline="", encoding="utf-8") as f:
    csv.writer(f).writerows([[v] for v in missing])
print(rows, "profiles;", len(missing), "not found")

Uma lista de 25 mil contas roda como 250 requisições em cerca de 13 segundos. Mantenha o id como texto ao abrir o profiles.csv em uma planilha: o Excel guarda só 15 dígitos de um número, e os IDs de usuário têm até 19. O guia sobre a API do Twitter em Python traz mais padrões para tentativas repetidas e armazenamento, e o guia ID de usuário do Twitter a partir do nome de usuário trata das listas que você só precisa converter em IDs.

#Atualize a lista e acompanhe o que mudou

Uma consulta de perfis é um instantâneo: cada execução registra as contagens como estão naquele momento, então rodar a mesma lista de forma agendada transforma instantâneos em histórico. Depois da primeira execução, consulte as contas pela coluna id do profiles.csv. Os IDs nunca mudam, então uma conta renomeada ainda volta, agora com o novo nome de usuário.

Dois instantâneos, comparados por ID, mostram o crescimento de seguidores, as mudanças de nome e as contas que sumiram:

import csv


def load(path):
    with open(path, newline="", encoding="utf-8") as f:
        return {row["id"]: row for row in csv.DictReader(f)}


old = load("profiles-2026-11-01.csv")
new = load("profiles-2026-11-02.csv")

for user_id, now in new.items():
    then = old.get(user_id)
    if then is None:
        continue                        # added to the list since
    if now["username"] != then["username"]:
        print(f"renamed: @{then['username']} is now @{now['username']}")
    gained = int(now["followers_count"]) - int(then["followers_count"])
    if gained:
        print(f"@{now['username']}: {gained:+,} followers")

gone = sorted(old.keys() - new.keys())
print(len(gone), "accounts no longer returned:", gone[:10])

Uma conta que deixa de voltar foi suspensa, apagada ou ficou indisponível desde a última execução. Os instantâneos diários de uma lista de leads ou de um elenco de criadores são onde a diferença de custo entre as duas APIs cresce mais rápido, porque o X cobra cada perfil de novo a cada dia UTC, enquanto a Sorsa API cobra cada requisição de 100. Planeje a atualização abaixo:

Para encontrar as contas que valem ser acompanhadas logo de início, o guia sobre como encontrar leads no Twitter monta listas de leads a partir de buscas no X, e a API de seguidores do Twitter devolve os seguidores de qualquer conta, 200 por página, cada um já com o perfil completo anexado.

#Quanto custa uma consulta de perfis em lote e quanto tempo leva

Na API oficial do X, uma consulta em lote custa US$ 10,00 por 1.000 perfis; na Sorsa API custa a partir de US$ 0,014 por 1.000, porque a Sorsa API cobra pela requisição de 100, não por cada perfil dentro dela.

O tempo é a segunda diferença. A API oficial do X deixa um app enviar 300 requisições de consulta por 15 minutos, então 1 milhão de perfis leva cerca de 8 horas e 20 minutos lá, mesmo com 100 por chamada. A Sorsa API roda 20 requisições por segundo em todos os planos, contas gratuitas incluídas: 2.000 perfis por segundo. A tabela coloca as duas lado a lado para quatro tamanhos de lista:

• 10 mil

  Custo na Sorsa API, a partir de

  US$ 0,14

  Tempo na Sorsa API

  cerca de 5 segundos

  Custo na API oficial do X

  US$ 100

  Tempo na API oficial do X

  dentro de uma janela de 15 minutos

• 100 mil

  Custo na Sorsa API, a partir de

  US$ 1,40

  Tempo na Sorsa API

  cerca de 50 segundos

  Custo na API oficial do X

  US$ 1.000

  Tempo na API oficial do X

  cerca de 50 minutos

• 500 mil

  Custo na Sorsa API, a partir de

  US$ 7,00

  Tempo na Sorsa API

  cerca de 4 minutos

  Custo na API oficial do X

  US$ 5.000

  Tempo na API oficial do X

  cerca de 4 horas

• 1 milhão

  Custo na Sorsa API, a partir de

  US$ 14,00

  Tempo na Sorsa API

  cerca de 8 minutos

  Custo na API oficial do X

  US$ 10.000

  Tempo na API oficial do X

  cerca de 8 horas e 20 minutos

O preço "a partir de" é a tarifa do maior plano, US$ 1,40 por 1.000 requisições; no Starter, o menor, 1.000 perfis custam US$ 0,049. Todo plano cobra do mesmo jeito: uma requisição devolve até 100 perfis, e requisições com falha nunca são cobradas.

Bom saber

Envie blocos cheios. Uma requisição com 3 contas custa o mesmo que uma com 100, então um trabalho que envia cada conta sozinha paga 100 vezes mais do que precisaria.

#Consulte seus primeiros 10 mil perfis

Uma consulta de perfis em lote se resume a uma requisição por 100 contas. Na API oficial do X, essa requisição custa US$ 1,00 e espera atrás de uma janela de 15 minutos depois de 300 delas. Para enriquecer uma lista de contas do X com dados de perfil, escolha a Sorsa API: o GET /info-batch devolve 100 perfis completos por requisição, a partir de US$ 0,014 por 1.000, a 20 requisições por segundo, com uma chave e sem conta de desenvolvedor. As 100 requisições grátis de uma conta nova consultam seus primeiros 10 mil perfis.

#FAQ