Skip to main content
Detecte novas publicações de contas, monitore palavras-chave e alimente sua aplicação com dados do X. Este guia usa consultas periódicas (polling) para montar um pipeline quase em tempo real. A latência depende do intervalo de consulta, da resposta da API e de quando o conteúdo aparece no feed ou índice de busca. Use checkpoints, paginação e deduplicação; não suponha que todo post novo estará na próxima resposta.
Prototipe grátis: as primeiras 100 requisições, sem cartão e sem validade, permitem validar os monitores e o encaminhamento a Slack ou Discord. Para uso contínuo, dimensione o plano pelo intervalo de polling.
Veja outras arquiteturas e exemplos no guia do blog.

Como funciona o polling

Ao contrário de streaming ou webhooks que enviam eventos, a Sorsa usa consultas periódicas:
  1. Consulte um endpoint a cada 1–30 segundos.
  2. Compare os IDs com os já vistos.
  3. Processe as novidades: armazene, envie alertas ou encaminhe a outros serviços.
  4. Repita.
IDs codificam o horário de criação e podem ser comparados com inteiros no Python ou BigInt no JavaScript. O maior ID é um checkpoint útil, mas resultados podem chegar atrasados ou fora de ordem. Em produção, consulte uma janela com sobreposição e deduplique. Persista e carregue o checkpoint explicitamente após reiniciar.

Escolha do endpoint

Nível 1: monitorar uma conta

O loop consulta a primeira página de /user-tweets e emite IDs posteriores ao último visto. Na primeira consulta bem-sucedida, define a referência sem emitir posts antigos. É um exemplo de desenvolvimento: pode perder dados se chegar mais de uma página entre consultas ou durante uma parada.

Python

JavaScript

Para 50 contas, seriam 50 loops e 50 vezes mais chamadas. Use listas para reduzir esse custo.

Nível 2: várias contas em uma chamada

Listas do X reúnem até 5.000 contas. /list-tweets retorna o feed recente combinado. É o padrão recomendado para várias contas; veja listas e comunidades.

Etapa 1: crie uma lista pública

  1. Acesse X Lists e crie uma lista.
  2. Adicione até 5.000 contas.
  3. Defina como Public. Listas privadas não são acessíveis.
  4. Copie o ID da URL: em https://x.com/i/lists/1234567890, o ID é 1234567890.

Etapa 2: consulte a lista

Consultar 50 contas a cada 10 segundos custa 50 × 8.640 = 432.000 chamadas/dia. Uma lista com as mesmas contas custa 8.640, redução de 50 vezes. Veja otimização.
Cada página traz até 20 publicações. Se o volume exceder isso por ciclo, reduza o intervalo para 2–3 segundos ou percorra next_cursor até cobrir os dados já vistos.

Nível 3: palavra-chave ou hashtag

Consulte /search-tweets com order: "latest".
Use os operadores de busca. Este exemplo busca menções em inglês com engajamento e exclui repostagens:

Encaminhar publicações a outros serviços

O loop produz eventos; o callback decide o destino. Ele pode chamar qualquer serviço HTTP.

Slack com Incoming Webhook

Discord

Telegram

Endpoint HTTP próprio

Estimativa de consumo

A tabela considera uma página por ciclo, horário fixo e nenhuma nova tentativa. Multiplique pela quantidade de monitores e acrescente páginas extras e repetições. Os exemplos esperam após cada resposta, então seus ciclos também incluem rede e processamento. Escolha pela latência tolerada e atividade do feed. Intervalos menores aumentam chamadas, mas não garantem disponibilidade imediata na busca. As 100 chamadas gratuitas servem para prototipar. Um monitor a cada 30–60 segundos cabe no Pro (100.000/mês); a cada 10 segundos, no Enterprise (500.000/mês). Vários monitores multiplicam o consumo. Veja preços.
Para cotas ou frequência acima dos planos padrão, fale com vendas ou use o Discord.

Preparação para produção

1. Persista last_seen_id

Sem checkpoint, reiniciar pode repetir alertas ou pular o intervalo de parada. Use arquivo, banco ou Redis.
Substitua last_seen_id = None por last_seen_id = load_state(). Salve o novo checkpoint só depois de processar ou enfileirar de forma durável todas as páginas. Não avance após falha de página ou entrega. Ao reiniciar, percorra o intervalo pendente antes de aceitar um checkpoint mais recente.

2. Espera exponencial em erros

Para falhas de rede, 429 e erros transitórios, aumente a espera gradualmente, com um teto. Veja códigos de erro.

3. Separe consulta e processamento

NLP, gravações e chamadas externas demoradas não devem bloquear o loop. Enfileire as publicações para outro worker.
Para cargas maiores, substitua a deque em memória por Redis, RabbitMQ, SQS ou outro broker.

4. Monitore o próprio monitor

Registre horário, quantidade de novidades, tempo de resposta e erros. Gere alerta se não houver uma consulta bem-sucedida nos últimos N minutos. Consulte também o status da Sorsa.

5. Trate casos especiais

Páginas excedentes e atrasos: percorra next_cursor até cobrir o período desde o checkpoint. Mantenha sobreposição e deduplique para não descartar resultados atrasados só porque têm IDs menores. Os exemplos de primeira página não implementam essa recuperação. Entrega do callback: confira o status dos webhooks e use tentativas limitadas ou fila durável. Sucesso na Sorsa não significa aceitação pelo Slack, Discord ou banco.
  • Posts excluídos: links podem retornar 404 entre consulta e processamento; trate como esperado.
  • Contas protegidas: se uma conta se tornar privada, /user-tweets retorna lista vazia; registre e continue.
  • Posts fixados: tweets[0] pode ser o fixado. Use max(int(t["id"]) for t in tweets) ou ordene por created_at.
  • Repostagens: tweet["retweeted_status"] é preenchido. Decida se deve incluí-las.
  • Respostas restritas: is_replies_limited indica restrição pelo autor.

Próximos passos