Como buscar tweets com uma API de busca do Twitter

#Como funciona uma API de busca do Twitter

Uma API de busca do Twitter é um endpoint que executa a busca do X sobre tweets públicos em seu nome. Você envia uma consulta, como "vector database" lang:en min_faves:20. De volta vem uma página de tweets que correspondem, com texto, data, contagens e autor, mais um cursor que busca a página seguinte.

Para testar uma consulta antes de escrever qualquer código, rode-a na ferramenta grátis Busca avançada do Twitter. Ela mostra os 20 primeiros posts encontrados, e cada filtro que você define escreve o seu operador na consulta, pronto para colar numa requisição.

Três ajustes decidem o que volta. A consulta escolhe tweets por palavras, contas, idioma, mídia e engajamento. A ordem é Top, os resultados mais engajados primeiro, ou Latest, os mais novos primeiro. A janela de datas fica dentro da consulta como since: e until: na sintaxe web do X, ou em parâmetros de tempo separados na API oficial do X.

A API oficial do X divide a busca em dois endpoints (documentação de busca do X (abre em uma nova aba)). O GET /2/tweets/search/recent cobre os últimos 7 dias e devolve de 10 a 100 posts por requisição; o GET /2/tweets/search/all volta até março de 2006 com até 500. Os dois exigem uma conta de desenvolvedor aprovada, um Project e um App e um Bearer token, e os dois cobram US$ 0,005 por cada post devolvido.

#Busque tweets com a Sorsa API em quatro passos

Para buscar tweets por código, use a Sorsa API, uma API e scraper do Twitter (X): resultados a partir de US$ 0,07 por 1.000, qualquer data até 2006 e 20 requisições por segundo em todos os planos. Ela precisa de um cabeçalho ApiKey em vez de uma conta de desenvolvedor e OAuth, lê a sintaxe de consulta da caixa de busca do x.com e nunca toca na sua conta do X.

1. Pegue uma chave. Cadastre-se e copie a chave de API no seu painel. As 100 requisições grátis já estão nela.

2. Escreva a consulta. Digite-a como faria no x.com: palavras, "exact phrases", from:, lang:, min_faves: e since:.

3. Envie a requisição. Envie a consulta por POST ao POST /search-tweets (abre em uma nova aba) num corpo JSON, com "order": "latest" para os tweets mais novos primeiro ou "popular" para o Top.

   curl -X POST "https://api.sorsa.io/v3/search-tweets" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "\"vector database\" lang:en min_faves:20", "order": "latest"}'
   

   {
     "tweets": [
       {
         "id": "2116173807613027825",
         "full_text": "Benchmarked three vector databases on 40M embeddings.",
         "created_at": "2026-10-30T14:22:07Z",
         "lang": "en",
         "likes_count": 214,
         "retweet_count": 37,
         "reply_count": 19,
         "quote_count": 6,
         "view_count": 18450,
         "bookmark_count": 92,
         "is_reply": false,
         "is_quote_status": false,
         "conversation_id_str": "2116173807613027825",
         "entities": [],
         "user": {
           "id": "1620350095193014349",
           "username": "indexlab_notes_daily",
           "display_name": "Index Lab Notes",
           "followers_count": 8312,
           "verified": false,
           "created_at": "2023-01-31T09:15:42Z"
         }
       }
     ],
     "next_cursor": "DAADDAABCgABHV3t2nWAJ8kKAAIdXcTm0Zvw"
   }
   

   Ver resposta completa

4. Siga o cursor. Cada tweet traz o perfil completo do autor, então não é preciso uma segunda consulta. Devolva o next_cursor no mesmo corpo para a página seguinte e pare quando uma resposta vier sem ele.

Uma resposta 403 significa que a chave está ausente ou sem requisições, e um 401 significa que a chave está errada. Um 429 significa mais de 20 requisições em um segundo: espere um segundo e envie de novo. Requisições com falha nunca são cobradas.

Cole a sua própria consulta abaixo para verificá-la e obter a requisição em curl, Python ou Node.js, com as aspas dentro do corpo JSON já escapadas. O verificador também sinaliza os nomes de operadores da API oficial do X, que a sintaxe web não usa.

curl -X POST "https://api.sorsa.io/v3/search-tweets" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "\"vector database\" lang:en min_faves:20", "order": "latest"}'

import requests

r = requests.post(
    "https://api.sorsa.io/v3/search-tweets",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={"query": '"vector database" lang:en min_faves:20',
          "order": "latest"},
    timeout=30,
)
page = r.json()
for t in page["tweets"]:
    print(t["user"]["username"], t["full_text"])
print(page.get("next_cursor"))

const res = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: { ApiKey: "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    query: '"vector database" lang:en min_faves:20',
    order: "latest",
  }),
});
const page = await res.json();
for (const t of page.tweets) console.log(t.user.username, t.full_text);
console.log(page.next_cursor);

#Escreva uma consulta que funcione em código

Uma consulta para o /search-tweets é a mesma string que você digitaria na caixa de busca do x.com, então dá para montá-la no navegador e colá-la na requisição sem mudar nada. Sete regras cobrem quase todos os problemas que os desenvolvedores encontram:

• Um espaço significa AND, o OR precisa estar em maiúsculas, um - no início exclui uma palavra ou um operador, e parênteses agrupam: (rust OR golang) -hiring.
• Frases exatas vão entre aspas duplas. Dentro de uma string JSON bruta essas aspas precisam de uma barra invertida, "\"vector database\""; em Python e Node.js passe um dict ou um objeto e a biblioteca as escapa por você.
• Hashtags, cashtags e menções entram como escritas: #buildinpublic, $NVDA, @acme_cloud_status. A consulta viaja num corpo JSON, então nada precisa de codificação de URL.
• As datas ficam na consulta: since:2026-10-01 inclui esse dia, until:2026-11-01 para antes dele, as duas em UTC.
• Os mínimos de engajamento são min_faves:, min_retweets: e min_replies:; um sinal de menos transforma um mínimo em máximo, como em -min_faves:1000.
• Os retweets nativos ficam de fora a menos que você acrescente include:nativeretweets, e -filter:replies mantém só os posts de nível principal.
• Cerca de 22 operadores cabem em uma consulta. Divida listas mais longas de contas ou palavras-chave entre várias consultas.

Cinco padrões cobrem a maior parte do que as equipes buscam, cada um pronto para colar no campo query:

# Mentions of a brand, without its own posts
("acme cloud" OR @acme_cloud_status) -from:acme_cloud_status

# The most liked posts on a topic
"vector database" min_faves:100 -filter:replies lang:en

# One account's posts on a subject in October
from:acme_cloud_status outage since:2026-10-01 until:2026-11-01

# Posts that link to a site
url:github.com rust -filter:replies

# Images under a hashtag
#buildinpublic filter:images

Todos os operadores, com suas particularidades e exemplos, estão na nossa lista de operadores de busca do Twitter.

#Pegue todas as páginas e mantenha a busca rodando

Para coletar mais de uma página, envie o mesmo corpo de novo com o next_cursor da última resposta e pare quando uma resposta não tiver nenhum. As páginas trazem cerca de 20 tweets e o tamanho varia, então uma página curta nunca significa que a busca acabou; só a falta de cursor significa.

O loop abaixo grava cada tweet num arquivo JSON Lines conforme ele chega e pula os IDs que já salvou. Um limite de páginas o interrompe, para que uma consulta ampla não gaste todas as suas requisições.

import json
import requests

API = "https://api.sorsa.io/v3/search-tweets"
HEADERS = {"ApiKey": "YOUR_API_KEY"}


def search(query, order="latest", max_pages=50):
    body = {"query": query, "order": order}
    for _ in range(max_pages):
        r = requests.post(API, json=body, headers=HEADERS, timeout=30)
        r.raise_for_status()
        page = r.json()
        yield from page.get("tweets", [])
        cursor = page.get("next_cursor")
        if not cursor:
            break
        body["next_cursor"] = cursor


seen = set()
with open("tweets.jsonl", "w", encoding="utf-8") as f:
    for t in search('"vector database" lang:en min_faves:20'):
        if t["id"] not in seen:
            seen.add(t["id"])
            f.write(json.dumps(t) + "\n")

const API = "https://api.sorsa.io/v3/search-tweets";
const headers = {
  ApiKey: "YOUR_API_KEY",
  "Content-Type": "application/json",
};

async function* search(query, order = "latest", maxPages = 50) {
  const body = { query, order };
  for (let i = 0; i < maxPages; i++) {
    const res = await fetch(API, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const page = await res.json();
    yield* page.tweets ?? [];
    if (!page.next_cursor) break;
    body.next_cursor = page.next_cursor;
  }
}

const query = '"vector database" lang:en min_faves:20';
for await (const t of search(query)) {
  console.log(t.id, t.user.username, t.full_text.slice(0, 60));
}

Uma busca que continua rodando é o mesmo loop num agendador. Peça os tweets mais novos, acrescente since_id: com o maior ID que você salvou da última vez, leia até o cursor acabar e salve o novo maior ID. Quando nada novo foi publicado, uma verificação custa uma única requisição, então verificações frequentes de uma consulta parada saem baratas.

import time

newest = None
while True:
    query = '"vector database" lang:en'
    if newest:
        query += f" since_id:{newest}"
    fresh = list(search(query))
    if fresh:
        newest = max(fresh, key=lambda t: int(t["id"]))["id"]
        print(len(fresh), "new tweets")
    time.sleep(300)

A busca funciona por polling: não há um stream para assinar. Para alertas, agendamentos e entrega no Slack ou por e-mail, o nosso guia de monitoramento do Twitter em tempo real monta o pipeline inteiro, e o guia da API do Twitter em Python acrescenta retentativas e buscas em paralelo.

Bom saber

Use "order": "latest" sempre que coletar ou contar tweets: ele percorre todas as correspondências do mais novo para trás. O "popular", a aba Top, devolve apenas as correspondências mais engajadas, então duas execuções do Top com a mesma consulta podem devolver conjuntos diferentes.

#Busque tweets por hashtag

Para buscar por hashtag, coloque a tag na consulta exatamente como você a digitaria, #buildinpublic. Ela encontra tweets em que a tag aparece como hashtag, com qualquer combinação de maiúsculas e minúsculas, e se combina com todos os outros operadores.

Acrescente as palavras simples com OR quando as pessoas também escrevem a frase sem a tag: (#buildinpublic OR "build in public") min_faves:10 -filter:replies lang:en. Para várias tags, junte-as com OR; para símbolos de ações ou moedas, use cashtags como $NVDA.

Pela Sorsa API, o # vai para o corpo JSON como está. Na requisição GET da API oficial do X ele precisa virar %23, porque um # sem codificação encerra a URL e o servidor nunca vê a tag. Para contar uma hashtag ao longo do tempo, rode uma busca Latest por dia com since: e until: e conte os tweets que cada dia devolve.

#Escolha o endpoint para a busca de que você precisa

A busca por palavras-chave é uma das cinco formas de encontrar tweets na Sorsa API. O endpoint certo depende do ponto de partida: palavras, uma conta, um conjunto de contas ou as próprias pessoas.

Cada um dos outros quatro lê um ponto de partida diferente. O POST /mentions (abre em uma nova aba) recebe um handle e devolve os tweets que o mencionam, com filtros de curtidas, respostas, retweets e data no corpo. O POST /search-users (abre em uma nova aba) encontra contas cujo nome ou bio correspondem a uma palavra. O POST /user-tweets (abre em uma nova aba) lê a timeline própria de uma conta, cerca de 20 tweets por requisição. Os membros de uma List do X voltam como um único feed no GET /list-tweets (abre em uma nova aba), então uma List de até 5.000 contas é acompanhada com uma requisição por página.

As equipes de marca costumam combinar dois deles: o /search-tweets para o que as pessoas dizem sobre um produto, e o /mentions para o que dizem à conta dele. O nosso guia da API de menções do Twitter cobre o segundo.

#Quanto custa buscar tweets

Na Sorsa API, os resultados de busca custam a partir de US$ 0,07 por 1.000 tweets: uma requisição devolve cerca de 20 tweets e é cobrada como uma requisição, seja qual for o conteúdo. A API oficial do X cobra cada post que devolve, US$ 0,005 por unidade, o que dá US$ 5,00 por 1.000 (lista de preços do X (abre em uma nova aba)).

O preço oficial sobe quando os autores vêm junto. A partir de 22 de novembro de 2026, o X cobra cada usuário devolvido por expansions a US$ 0,010 (aviso do X de 23 de outubro (abre em uma nova aba)), então 1.000 resultados com um autor diferente cada podem custar US$ 15,00. A Sorsa API coloca o perfil completo do autor dentro de cada tweet sem custo extra.

O volume também tem um teto ali: o pagamento por uso para em 3 milhões de leituras de posts por mês, e acima disso o X vende só contratos Enterprise. A Sorsa API não tem teto de 3 milhões: os planos chegam a 10 milhões de requisições por mês, e as suas 100 requisições grátis cobrem cerca de 2.000 resultados de busca, sem cartão. O detalhamento completo dos preços da API do X traz todas as tarifas oficiais.

#A busca da API oficial do X, lado a lado

A busca da API oficial do X custa cerca de 71 vezes mais por 1.000 resultados do que a Sorsa API. A busca recente dela enxerga só os últimos 7 dias e permite 450 requisições a cada 15 minutos por app. A tabela coloca os três endpoints de busca lado a lado, com os limites oficiais da tabela de rate limits do X (abre em uma nova aba).

• Datas cobertas

  /search-tweets da Sorsa API

  Até março de 2006

  Busca recente do X

  Últimos 7 dias

  Busca em todo o arquivo do X

  Até março de 2006

• Resultados por requisição

  /search-tweets da Sorsa API

  Cerca de 20

  Busca recente do X

  10 a 100

  Busca em todo o arquivo do X

  10 a 500

• Rate limit

  /search-tweets da Sorsa API

  20 requisições por segundo por chave

  Busca recente do X

  450 requisições a cada 15 minutos por app

  Busca em todo o arquivo do X

  1 requisição por segundo, 300 a cada 15 minutos

• Preço por 1.000 resultados

  /search-tweets da Sorsa API

  A partir de US$ 0,07

  Busca recente do X

  US$ 5,00

  Busca em todo o arquivo do X

  US$ 5,00

• Perfil do autor

  /search-tweets da Sorsa API

  Dentro de cada tweet

  Busca recente do X

  Cobrado a US$ 0,010 cada a partir de 22 de nov. de 2026

  Busca em todo o arquivo do X

  Cobrado a US$ 0,010 cada a partir de 22 de nov. de 2026

• Sintaxe da consulta

  /search-tweets da Sorsa API

  Busca web do x.com

  Busca recente do X

  Operadores v2, 512 caracteres

  Busca em todo o arquivo do X

  Operadores v2, 1.024 caracteres

• Configuração

  /search-tweets da Sorsa API

  Uma chave de API

  Busca recente do X

  Conta de desenvolvedor, App, Bearer token

  Busca em todo o arquivo do X

  Conta de desenvolvedor, App, Bearer token

Os endpoints oficiais também devolvem por padrão só id e text: datas, contagens e autores só voltam quando tweet.fields, expansions e user.fields os pedem. Na Sorsa API todo tweet chega com todos os campos.

#Sintaxe web contra os operadores da API oficial do X

A API oficial do X lê os seus próprios nomes de operadores, então uma consulta copiada da caixa de busca do x.com pode falhar ali. Ela rejeita min_faves: e min_retweets: com um erro 400, e recebe as datas como parâmetros start_time e end_time, não na consulta. A Sorsa API aceita a sintaxe web, então a coluna da esquerda roda nela como está escrita.

• Pelo menos 20 curtidas

  Sintaxe web (x.com, Sorsa API)

  min_faves:20

  API oficial do X v2

  min_likes:20

• Pelo menos 5 reposts

  Sintaxe web (x.com, Sorsa API)

  min_retweets:5

  API oficial do X v2

  min_reposts:5

• Só outubro de 2026

  Sintaxe web (x.com, Sorsa API)

  since:2026-10-01 until:2026-11-01

  API oficial do X v2

  parâmetros start_time e end_time

• Só respostas

  Sintaxe web (x.com, Sorsa API)

  filter:replies

  API oficial do X v2

  is:reply

• Posts com mídia ou links

  Sintaxe web (x.com, Sorsa API)

  filter:media, filter:links

  API oficial do X v2

  has:media, has:links

• Retweets

  Sintaxe web (x.com, Sorsa API)

  Ficam de fora por padrão

  API oficial do X v2

  Fora das buscas por palavra-chave desde 4 de maio de 2026

• Palavras, contas, idioma

  Sintaxe web (x.com, Sorsa API)

  from:, to:, #, @, "phrase", lang:

  API oficial do X v2

  Os mesmos

Duas mudanças em 2026 explicam por que guias mais antigos discordam. O X desligou min_likes:, min_replies: e min_reposts: em 19 de janeiro de 2026. Ele os trouxe de volta em 4 de maio, quando a busca passou para um novo índice que também tirou os retweets dos resultados por palavra-chave (changelog do X (abre em uma nova aba)). As páginas e respostas de IA que dizem que a API oficial do X ignora filtros de engajamento descrevem os meses intermediários.

Vai migrar uma integração inteira dos endpoints oficiais? O nosso guia para migrar da API oficial do X mapeia cada parâmetro e operador da v2 para a Sorsa API.

#Comece a buscar tweets hoje

Buscar tweets por código se resume a uma consulta e um cursor. Com a Sorsa API, a consulta que você já digita no x.com vai ao POST /search-tweets e devolve cerca de 20 tweets por requisição com seus autores, de qualquer data até 2006. Os resultados custam a partir de US$ 0,07 por 1.000, contra US$ 5,00 na API oficial do X, e as suas 100 requisições grátis cobrem os primeiros 2.000.

#FAQ