Obtenha dados públicos de perfil do X com Python para enriquecimento de leads

Antes de mandar e-mail para um criador ou adicionar um lead a uma lista, você quer o básico: quantos seguidores a conta realmente tem, se a conta é verificada, o que diz a bio, quando foi criada. Isso é uma consulta de perfil público, não um projeto de pesquisa, e o /v1/x responde exatamente isso com uma requisição.

A própria plataforma de desenvolvedores do X pode responder a mesma pergunta, mas só depois de você registrar um app, ser aprovado, e escolher um tier pago, um custo de configuração real se tudo que você precisa é a contagem de seguidores de alguns leads por semana. Esse endpoint pula isso: é uma chamada REST normal sobre dados de perfil público, cobrada por consulta em vez de por assinatura.

Um parâmetro: profileId

O único parâmetro é profileId, em camelCase, e é o username sem o @. Passe elonmusk, não @elonmusk e não uma URL de perfil. Se a sua lista de origem tem usernames copiados direto do X ou de um link de perfil, remova o @ e qualquer URL ao redor antes de montar a requisição, já que profileId é documentado como o handle puro.

import requests

API_KEY = "faf_live_..."  # sua chave FastAF

resp = requests.get(
    "https://api.fastaf.co/v1/x",
    params={"profileId": "elonmusk"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=60,
)
resp.raise_for_status()

profile = resp.json()["profile"]
stats = profile["stats"]

print(f'{profile["name"]} ({profile["username"]})')
print(f'verified: {profile["is_blue_verified"]}')
print(f'followers: {stats["followers"]:,}  following: {stats["following"]:,}  tweets: {stats["tweets"]:,}')
print(f'bio: {profile["description"]}')
print(f'created: {profile["created_at"]}')

Isso é 5 créditos. Tudo aninha primeiro dentro de um objeto profile, e os contadores aninham de novo um nível mais fundo dentro de profile["stats"], que é a parte que as pessoas chutam errado antes de checar: followers não é de nível superior.

O que você realmente recebe

Rodar a chamada acima contra uma conta real e conhecida retornou um objeto profile com: name, username (esse vem com o @ incluso, mesmo o parâmetro da requisição não recebendo ele), user_id, description (a bio), location, website, created_at, is_blue_verified, verified_type, protected, possibly_sensitive, e campos de imagem (profile_image, profile_banner). Aninhados sob stats: followers, following, tweets, e creator_subscriptions. Para essa conta em particular os números foram uma contagem de followers acima de 241 milhões, following em 1.396, e tweets em 107.673, todos inteiros puros, sem formatação para remover. Isso já é o suficiente para construir uma regra de triagem de verdade, por exemplo rejeitar qualquer coisa abaixo de um piso de seguidores, ou uma checagem de idade de conta calculada a partir de created_at.

location voltou null nessa conta, o que é um lembrete de que os campos de perfil só são tão completos quanto o que a pessoa preencheu no X: trate todo campo, exceto o básico de identidade (name, username, user_id), como opcional quando você escrever o código que consome isso.

O que ele não faz

Seja claro consigo mesmo sobre o escopo antes de construir um pipeline em cima disso: /v1/x retorna um perfil, uma vez, por chamada. Ele não retorna os posts daquela conta, não retorna uma lista de seguidores dela ou de quem ela segue, e não é uma busca: você já precisa do username exato, vindo de um formulário de lead, um CSV, uma menção, de onde quer que a sua lista venha. Se o seu fluxo precisa de “achar contas falando sobre X” em vez de “me conte sobre essa conta específica”, esse endpoint é a ferramenta errada para essa etapa.

Também é um snapshot, não uma assinatura: nada te empurra uma atualização quando uma contagem de seguidores cruza um limite ou uma bio muda. Se você precisa disso, chame de novo no seu próprio cronograma e compare o stats que voltar com o que você guardou da última vez, do mesmo jeito que você acompanharia qualquer outro número que muda com o tempo.

Triagem e enriquecimento, na prática

O padrão comum é um job em lote: entra uma lista de usernames, sai uma lista pontuada ou filtrada. Mantenha o filtro em si simples e específico para o que você realmente precisa, um piso de seguidores, uma checagem de verificação, um corte de idade de conta, em vez de tentar calcular um único “influencer score” a partir de campos que nunca foram desenhados para se combinar em um só.

def enrich(usernames, min_followers=10_000):
    qualified = []
    for handle in usernames:
        resp = requests.get(
            "https://api.fastaf.co/v1/x",
            params={"profileId": handle},
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=60,
        )
        resp.raise_for_status()
        p = resp.json()["profile"]
        if p["stats"]["followers"] >= min_followers:
            qualified.append({
                "username": p["username"],
                "followers": p["stats"]["followers"],
                "verified": p["is_blue_verified"],
                "bio": p["description"],
            })
    return qualified

Envolva cada chamada num try/except em produção: uma conta desativada ou suspensa é uma possibilidade real em qualquer lista que você não gerou você mesmo, e você quer que isso pule uma linha, não pare o lote.

Quanto isso custa

Volume	Créditos	Pacote que cobre	Custo
500 leads, triagem única	2.500	Growth, $29	~$0,97 do pacote
5.000 perfis enriquecidos em 30 dias	25.000	Growth, $29	~$9,67 do pacote
50.000 perfis enriquecidos em 30 dias	250.000	Scale, $99	~$82,50 do pacote

Requisições com falha nunca são cobradas: os créditos são reservados quando a requisição começa e devolvidos se ela não voltar com um resultado. O plano gratuito é de 500 créditos sem cartão, o que cobre 100 consultas de perfil, de sobra para checar a cobertura de campos na sua própria lista antes de se comprometer com um cronograma.