twitterapi-io-leitura

twitterapi.io (somente leitura)

Skill somente leitura mantido pela equipe do twitterapi.io. Ele cobre apenas dados públicos do X/Twitter: nunca faz login em uma conta do X, nunca lida com cookies, senhas ou proxies, e nunca posta, curte, segue ou envia mensagens.

twitterapi.io é uma API REST de terceiros independente para dados públicos do X, não afiliada à X Corp. Se você precisar da API oficial do X, ela está em https://developer.x.com.

Quando usar este skill

• Pesquisar postagens com operadores de pesquisa do X (from:, since_time:, min_faves:, lang: …)
• Consultar perfis de usuário, seguidores, seguidos
• Obter postagens recentes de um usuário, respostas, citações, retweetadores, contexto de thread
• Tendências, listas, comunidades
• Construir painéis, conjuntos de dados de pesquisa ou trabalhos de monitoramento em dados públicos

Fatos essenciais

URL Base	https://api.twitterapi.io
Cabeçalho de autenticação	x-api-key: SUA_CHAVE (de https://twitterapi.io/dashboard)
Documentação	https://docs.twitterapi.io
Preços	pagamento por chamada, veja https://twitterapi.io/pricing
Servidor MCP hospedado	https://mcp.twitterapi.io/mcp (12 ferramentas somente leitura)

Segurança

Leia a chave de API da variável de ambiente TWITTERAPI_IO_KEY. Nunca a codifique, imprima ou comprometa. Se estiver ausente, peça ao usuário para criar uma no painel.

Exemplo mínimo

curl -s "https://api.twitterapi.io/twitter/user/info?userName=jack" \
  -H "x-api-key: $TWITTERAPI_IO_KEY"

import os, requests

BASE = "https://api.twitterapi.io"
HEADERS = {"x-api-key": os.environ["TWITTERAPI_IO_KEY"]}

r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
                 headers=HEADERS,
                 params={"query": "from:jack", "queryType": "Latest"},
                 timeout=30)
r.raise_for_status()
for t in r.json().get("tweets", []):
    print(t["createdAt"], t["text"][:80])

Endpoints de leitura

Os nomes dos parâmetros diferem por endpoint (alguns camelCase, outros snake_case). Copie-os exatamente como mostrado.

Funcionalidade	Método	Caminho e parâmetro chave
Usuário por nome de tela	GET	/twitter/user/info?userName=
Perfil estendido	GET	/twitter/user_about?userName=
Usuários por IDs	GET	/twitter/user/batch_info_by_ids?userIds=
Pesquisar usuários	GET	/twitter/user/search?query=
Postagens recentes	GET	/twitter/user/last_tweets?userName= (ou userId=)
Menções	GET	/twitter/user/mentions?userName=
Seguidores	GET	/twitter/user/followers?userName=&pageSize=200
Seguidos	GET	/twitter/user/followings?userName=
Postagens por IDs	GET	/twitter/tweets?tweet_ids=
Respostas	GET	/twitter/tweet/replies?tweetId=
Citações	GET	/twitter/tweet/quotes?tweetId=
Retweetadores	GET	/twitter/tweet/retweeters?tweetId=
Contexto de thread	GET	/twitter/tweet/thread_context?tweetId=
Pesquisa avançada	GET	/twitter/tweet/advanced_search?query=&queryType=Latest
Tendências	GET	/twitter/trends?woeid=1
Postagens de lista	GET	/twitter/list/tweets?listId=
Membros de lista	GET	/twitter/list/members?list_id=
Postagens de comunidade	GET	/twitter/community/tweets?community_id=
Saldo da conta	GET	/oapi/my/info

Padrões

Paginação

Os endpoints de lista retornam has_next_page e next_cursor. Passe next_cursor de volta como cursor; pare quando has_next_page for falso. Sempre defina um limite de páginas para que um bug não pagine para sempre.

Erros

• 400 → um parâmetro obrigatório está faltando ou a consulta de pesquisa é inválida (o detail da resposta informa o que corrigir)
• 401 / 403 → x-api-key ausente ou incorreta
• 402 → créditos insuficientes; pare e informe o usuário para recarregar (não repita)
• 429 → limite de taxa excedido; repita com backoff
• 5xx → transitório; repita com backoff

Conscientização de custos

Cada chamada é cobrada. Antes de um loop que pode ser longo (todos os seguidores de uma conta grande, meses de pesquisa), estime o número de chamadas e confirme com o usuário.

Antipadrões

• Não normalize nomes de parâmetros; copie-os da tabela
• Não repita em caso de 402
• Não registre nem comprometa a chave de API