API de monitoramento de hashtags do Twitter

#Como o monitoramento de hashtags funciona por meio de uma API

Monitorar uma hashtag é coletar todos os posts públicos que levam uma mesma tag durante um período e transformá-los em três respostas: quantos apareceram por dia, quem os postou e quais foram os mais lidos. Nenhuma API do X tem um endpoint para hashtags como tal. Toda rota passa pela busca, com a tag escrita na consulta.

Para uma olhada rápida sem código, a ferramenta gratuita Análise de hashtags do Twitter mostra os posts por hora, as maiores vozes e os posts de destaque de qualquer tag nas últimas 24 horas ou nos últimos 7 dias. O resto deste guia monta o mesmo relatório em código, para qualquer período e qualquer número de tags.

Em uma consulta de busca, #tidewaterdevdays encontra posts em que o X reconheceu a palavra como hashtag, em qualquer combinação de maiúsculas e minúsculas. A palavra solta tidewaterdevdays também pega posts que a escrevem sem o #, então um relatório de campanha que deve contar só posts com a tag mantém o #. Uma tag termina no primeiro caractere que não é letra, dígito nem sublinhado, então #c++ é a tag #c, enquanto tags em japonês, árabe ou qualquer outro alfabeto funcionam como estão escritas. Todos os outros filtros, de idioma a mínimo de curtidas, estão no nosso guia de operadores de busca do Twitter.

A busca tem duas ordens. Latest percorre todos os resultados do mais novo para trás, que é o que a contagem precisa. Top devolve só os resultados mais engajados, então serve bem para uma lista dos melhores e mal para um contador.

A API oficial do X também tem dois endpoints de contagem: GET /2/tweets/counts/recent para os últimos 7 dias e GET /2/tweets/counts/all para o arquivo, com totais por minuto, hora ou dia (visão geral das contagens do X (abre em uma nova aba)). Eles devolvem números e nada mais: sem posts, sem autores, sem visualizações. A própria nota do X acrescenta que as contagens podem não bater exatamente com os resultados da busca. Um monitor que precisa dizer quem impulsionou uma tag, ou qual post a levou, lê os próprios posts.

#Monitore uma hashtag com a Sorsa API em quatro passos

A Sorsa API, uma API e scraper do Twitter (X), roda a sintaxe de busca do X por um único endpoint, POST /search-tweets, e devolve cada post com o perfil completo do autor. Uma passada pelas páginas produz as três saídas, então a contagem, o ranking de autores e os posts de destaque nunca precisam de requisições separadas.

Para monitorar hashtags, use a Sorsa API: uma chave de API e nenhuma conta de desenvolvedor, cerca de 20 posts por requisição com os autores incluídos, a partir de US$ 0,07 por 1.000 posts e 20 requisições por segundo em todos os planos.

1. Obtenha uma chave. Cadastre-se e copie sua chave de API no painel. As primeiras 100 requisições são grátis, sem cartão.

2. Envie a consulta. Coloque a tag e o período em query e peça os posts mais novos primeiro. O # vai no corpo JSON como está, sem codificação de URL.

   curl -X POST "https://api.sorsa.io/v3/search-tweets" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "#tidewaterdevdays since:2026-10-19 until:2026-11-02",
          "order": "latest"}'
   

   {
     "tweets": [
       {
         "id": "2115444854355529755",
         "full_text": "Day one of #tidewaterdevdays, slides below #devrel",
         "created_at": "2026-10-28T14:05:31Z",
         "lang": "en",
         "likes_count": 312,
         "retweet_count": 41,
         "reply_count": 18,
         "quote_count": 6,
         "view_count": 28410,
         "is_reply": false,
         "user": {
           "id": "1366674638239301632",
           "username": "maren_codes_at_night",
           "display_name": "Maren",
           "followers_count": 18240,
           "verified": false
         }
       }
     ],
     "next_cursor": "DAADDAABCgABHVvqb2SWYBsKAAIdW-l6pZbQkAAIAAIAAAAC"
   }
   

   Ver resposta completa

3. Siga o cursor. Envie next_cursor de volta no corpo da requisição seguinte até uma resposta vir sem ele. O tamanho das páginas varia, então pare quando o cursor faltar, nunca por causa de uma página curta. Um 403 significa que a chave está ausente ou sem requisições; um 429 significa mais de 20 requisições em um segundo, então espere um segundo e tente de novo.

4. Agrupe os posts. Mantenha uma linha por ID de post e depois conte por dia e por autor. O script abaixo faz o trabalho inteiro e imprime o relatório.

   import re
   from collections import Counter
   from datetime import datetime, timezone
   
   import requests
   
   URL = "https://api.sorsa.io/v3/search-tweets"
   HEADERS = {"ApiKey": "YOUR_API_KEY"}
   TAG = re.compile(r"#\w+")
   
   
   def collect(query):
       """Yield every post the search returns, newest first."""
       body = {"query": query, "order": "latest"}
       while True:
           r = requests.post(URL, headers=HEADERS, json=body, timeout=30)
           r.raise_for_status()
           page = r.json()
           yield from page.get("tweets", [])
           cursor = page.get("next_cursor")
           if not cursor:
               return
           body["next_cursor"] = cursor
   
   
   def utc_day(post):
       stamp = post["created_at"].replace("Z", "+00:00")
       t = datetime.fromisoformat(stamp)
       return t.astimezone(timezone.utc).date().isoformat()
   
   
   def track(tag, since, until):
       posts = {}
       for p in collect(f"{tag} since:{since} until:{until}"):
           posts[p["id"]] = p  # one row per post ID
       per_day, by_author, views, tags = Counter(), Counter(), Counter(), Counter()
       for p in posts.values():
           per_day[utc_day(p)] += 1
           by_author[p["user"]["username"]] += 1
           views[p["user"]["username"]] += p.get("view_count") or 0
           tags.update(m.lower() for m in TAG.findall(p["full_text"]))
       top = sorted(posts.values(), key=lambda p: p.get("view_count") or 0)
       return per_day, by_author, views, tags, top[::-1][:10]
   
   
   per_day, by_author, views, tags, top = track(
       "#tidewaterdevdays", "2026-10-19", "2026-11-02")
   for day, n in sorted(per_day.items()):
       print(day, n)
   print("Top authors:", by_author.most_common(5))
   print("Most viewed:", views.most_common(5))
   print("Related tags:", tags.most_common(10))
   

   const URL = "https://api.sorsa.io/v3/search-tweets";
   const headers = {
     ApiKey: "YOUR_API_KEY",
     "Content-Type": "application/json",
   };
   
   async function track(tag, since, until) {
     const body = { query: `${tag} since:${since} until:${until}`,
       order: "latest" };
     const posts = new Map();
     do {
       const res = await fetch(URL, {
         method: "POST", headers, body: JSON.stringify(body) });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       const page = await res.json();
       for (const p of page.tweets ?? []) posts.set(p.id, p);
       body.next_cursor = page.next_cursor;
     } while (body.next_cursor);
   
     const perDay = {}, byAuthor = {};
     for (const p of posts.values()) {
       const day = new Date(p.created_at).toISOString().slice(0, 10);
       perDay[day] = (perDay[day] ?? 0) + 1;
       const who = p.user.username;
       byAuthor[who] = (byAuthor[who] ?? 0) + 1;
     }
     return { perDay, byAuthor, total: posts.size };
   }
   
   const report = await track("#tidewaterdevdays", "2026-10-19",
     "2026-11-02");
   console.log(report.perDay, report.total);
   console.log(Object.entries(report.byAuthor)
     .sort((a, b) => b[1] - a[1]).slice(0, 5));
   

Os parâmetros e os campos de resposta do endpoint estão na referência de POST /search-tweets (abre em uma nova aba). Para tudo o que a busca faz além de hashtags, de consultas por palavra-chave às outras formas de encontrar posts, veja o guia da API de busca do Twitter.

#Conte os posts de uma hashtag por dia

Para contar uma hashtag por dia, leia todos os posts do período com a ordem Latest, mantenha uma linha por ID de post e agrupe as linhas pela data UTC do created_at de cada post. A data na consulta só decide quais posts você busca; a data de cada post decide onde ele é contado.

Essa separação importa nas bordas. since: e until: funcionam em UTC, e until: deixa de fora a própria data, então since:2026-10-28 until:2026-10-29 é apenas 28 de outubro. Posts perto da meia-noite ainda podem aparecer em uma janela vizinha, e é por isso que o script conta pelo created_at e descarta repetições pelo ID em vez de confiar na janela.

Um período longo é lido mais depressa como uma janela por dia. Os dias não dependem uns dos outros, então rodam lado a lado: uma chave atende 20 requisições por segundo, cerca de 400 posts por segundo, e um ano de uma tag com 5.000 posts por dia é lido em cerca de 76 minutos. O histórico vai até 2006, então um monitor iniciado hoje consegue contar a campanha do ano passado com a mesma facilidade que a desta semana.

Três escolhas de consulta mudam a contagem, então anote-as ao lado do número:

• Reposts. A busca do X deixa de fora os reposts simples por padrão e mantém as respostas. Acrescente include:nativeretweets para contar também os reposts, e distinga-os por retweeted_status.
• Respostas. Acrescente -filter:replies para contar só posts que iniciam uma conversa.
• Variantes. Junte grafias e tags irmãs com OR: (#tidewaterdevdays OR #tidewater2026).

Neste exemplo, uma tag fictícia de conferência sobe de 420 posts em 19 de outubro para 4.812 em 28 de outubro, seu primeiro dia, e soma cerca de 25 mil posts de 9.214 autores em 14 dias. Ler todos eles custa a partir de US$ 1,76 na Sorsa API, contra US$ 126 na API oficial do X.

Bom saber

O X data todo post em UTC, então um dia no relatório é um dia UTC. Para uma equipe em Nova York, 28 de outubro no horário local vai das 04:00 UTC do dia 28 às 04:00 UTC do dia 29: converta o created_at para o seu fuso antes de agrupar se o relatório seguir os dias locais.

#Encontre os maiores autores, posts e hashtags relacionadas

Os maiores autores saem de agrupar os mesmos posts por user.username: conte os posts de cada conta e depois some as visualizações e curtidas, porque a conta que mais posta e a conta mais lida raramente são a mesma. Toda métrica de que um relatório de hashtag precisa vem de campos que chegam com cada post, então nenhuma delas custa uma requisição extra.

• Posts por dia

  Como calcular

  IDs de post por data UTC

  Campo

  created_at

• Posts por hora

  Como calcular

  IDs de post por hora UTC, para ver um pico se formar

  Campo

  created_at

• Autores únicos

  Como calcular

  Contas distintas

  Campo

  user.id

• Maiores autores por posts

  Como calcular

  Posts por conta

  Campo

  user.username

• Maiores autores por alcance

  Como calcular

  Seguidores de cada conta

  Campo

  user.followers_count

• Visualizações

  Como calcular

  Soma das visualizações dos posts com a tag

  Campo

  view_count

• Engajamento

  Como calcular

  Curtidas, reposts, respostas e quotes

  Campo

  likes_count, retweet_count, reply_count, quote_count

• Idiomas

  Como calcular

  Posts por idioma

  Campo

  lang

• Hashtags relacionadas

  Como calcular

  Tags encontradas no texto

  Campo

  full_text

As visualizações são o número que o X mostra sob cada post. Somadas ao longo de uma tag, são o dado público mais próximo das impressões dela, e superam o "alcance" por soma de seguidores com que muitos relatórios abrem, já que os seguidores não veem todos os posts. Guarde os dois e diga qual é qual.

Compare posts com autores únicos antes de confiar em um pico. Milhares de posts de algumas dezenas de contas são um empurrão; uma tag usada por milhares de pessoas, uma vez cada, é uma conversa. Ordenar os autores por visualizações em vez de por número de posts costuma levar as vozes de verdade ao topo.

As hashtags relacionadas vêm do texto dos posts. O campo entities lista mídia e links, não tags, então o script tira cada #palavra do full_text com uma expressão regular e as conta. Os vizinhos mais comuns de uma tag de campanha mostram as tags irmãs a acrescentar à consulta e as comunidades que ela alcançou.

#Quanto custa monitorar hashtags

Ler os posts de uma hashtag custa a partir de US$ 0,07 por 1.000 na Sorsa API e US$ 5,00 por 1.000 na API oficial do X, cerca de 70x mais, antes da cobrança do X pelos autores. A partir de 22 de novembro de 2026, o X cobra cada autor devolvido com um post a US$ 0,010, a tarifa de leitura de usuário, então os posts com seus autores custam até US$ 15,00 por 1.000 lá (aviso do X de 23 de outubro (abre em uma nova aba)). Na Sorsa API o perfil do autor vem dentro de cada post sem custo extra.

A rota oficial também exige uma conta de desenvolvedor aprovada, um app OAuth e créditos pré-pagos. O plano de pagamento por uso dela para em 3 milhões de leituras de posts por mês; uma tag movimentada além disso precisa de um contrato Enterprise a partir de cerca de US$ 42.000 por mês (tabela de preços do X (abre em uma nova aba)). A Sorsa API usa uma chave em um header, nunca pede seu login do X, e o preço por 1.000 posts cai à medida que os planos crescem.

A maioria das tags é menor do que parece. Uma tag de produto ou de evento com algumas centenas de posts por dia precisa de cerca de 15 requisições por dia para ser monitorada, e as 100 requisições grátis leem cerca de 2.000 posts, o bastante para dimensionar qualquer tag antes de pagar.

#Mantenha um monitor de hashtag em funcionamento

Para manter um monitor atualizado, rode-o em intervalos e peça só posts mais novos que o último que você guardou, com since_id: definido como o ID desse post: #tidewaterdevdays since_id:2117039272883781709. Cada execução então lê só as páginas novas, e uma hora tranquila custa uma requisição.

Escolha o intervalo pelo ritmo da tag: de hora em hora para uma campanha em andamento, a cada poucos minutos durante um evento ao vivo. A Sorsa API funciona por polling; ela não tem stream nem webhooks, e a 20 requisições por segundo uma consulta de dezenas de tags ainda termina em segundos. Para alertas no Slack ou por e-mail quando uma tag dispara, nosso guia de monitoramento do Twitter em tempo real monta o agendador e a entrega.

Guarde cada post em uma tabela com o ID como chave e atualize a linha quando vir o post de novo. As visualizações e curtidas continuam crescendo por dias depois que um post aparece, então releia os últimos dois ou três dias antes de publicar os números finais de uma campanha.

Para saber quando uma tag estoura, confira as listas de trending topics do X nos lugares que importam para você: GET /trends devolve a lista atual de um lugar, e o guia da API de trends do Twitter mostra como acompanhá-la. Para várias tags ao mesmo tempo, rode uma consulta por tag lado a lado, para que cada contagem fique separada.

#Comece a monitorar sua hashtag

Um monitor de hashtag é uma busca pela tag com a ordem Latest, cada página lida uma vez e os posts contados por dia UTC e por autor. A Sorsa API faz a leitura a partir de US$ 0,07 por 1.000 posts com todos os autores incluídos, 20 requisições por segundo em todos os planos e histórico desde 2006; seus primeiros 2.000 posts são grátis.

#Perguntas frequentes