API de menções do Twitter para qualquer conta do X

#O que uma API de menções do Twitter devolve

Uma API de menções do Twitter é um endpoint que recebe uma conta e devolve, como páginas de JSON, os posts públicos que marcam o @handle dela, dos mais novos para os mais antigos. Uma marcação conta onde quer que esteja: no começo de uma resposta, no meio de uma frase ou em uma fileira de vários handles.

Para ver as menções recentes de uma conta sem código, o Verificador de menções do Twitter, gratuito, as lista por período e mínimo de curtidas. O resto deste guia faz o mesmo trabalho em código, para qualquer número de contas e de páginas.

Cada menção volta como um post completo: o texto e o horário, as curtidas, respostas, reposts, quotes e visualizações, se ele responde a alguém e quem o escreveu. Posts de contas protegidas nunca aparecem. Um post que cita uma marca sem o @ não é uma menção: ele exige uma busca por palavra-chave, tratada mais adiante.

Na API oficial do X, as menções vêm de GET /2/users/{id}/mentions (referência do X (abre em uma nova aba)). Ele recebe o ID numérico de usuário da conta, então um handle exige antes uma consulta de usuário. Cada requisição devolve de 5 a 100 posts, e a timeline guarda apenas as 800 menções mais recentes de uma conta (visão geral de timelines do X (abre em uma nova aba)). Um post volta só com o ID e o texto; datas, contagens e o autor chegam apenas quando tweet.fields, expansions e user.fields os pedem.

O tempo é o único filtro que o endpoint oficial aceita: start_time, end_time, since_id e until_id. Ele não tem opção para curtidas nem respostas, então uma central de suporte e uma equipe de relações públicas baixam o mesmo feed e o ordenam do lado delas.

#Obtenha menções por handle com a Sorsa API

Para puxar menções em código, use a Sorsa API, uma API e scraper do Twitter (X): POST /mentions devolve as menções de qualquer conta a partir de US$ 0,07 por 1.000, contra US$ 5,00 na API oficial do X. Ele recebe o handle como você o digita e filtra por curtidas, respostas, retweets e data no mesmo corpo JSON. Um único header ApiKey substitui uma conta de desenvolvedor e o OAuth, e a sua conta do X nunca entra no processo.

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

2. Indique a conta. Coloque o handle em query, sem o @, por exemplo northwind_billing. Pode ser a sua marca, um cliente ou um concorrente: qualquer conta pública serve.

3. Envie a requisição. Faça POST do corpo para POST /mentions (abre em uma nova aba), com "order": "latest" para trazer as menções mais novas primeiro.

   curl -X POST "https://api.sorsa.io/v3/mentions" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "northwind_billing", "order": "latest"}'
   

   {
     "tweets": [
       {
         "id": "2116933823886904728",
         "full_text": "@northwind_billing invoices still pending, is sync down?",
         "created_at": "2026-11-01T16:42:09Z",
         "lang": "en",
         "likes_count": 14,
         "retweet_count": 2,
         "reply_count": 3,
         "quote_count": 0,
         "view_count": 2310,
         "bookmark_count": 1,
         "is_reply": false,
         "is_quote_status": false,
         "conversation_id_str": "2116933823886904728",
         "entities": [],
         "user": {
           "id": "1587702913445103616",
           "username": "ops_notes_by_priya",
           "display_name": "Priya, ops notes",
           "followers_count": 4180,
           "verified": false,
           "created_at": "2022-11-02T08:31:44Z"
         }
       },
       {
         "id": "2116909085882164728",
         "full_text": "@northwind_billing the usage export saved me an afternoon",
         "created_at": "2026-11-01T15:03:51Z",
         "lang": "en",
         "likes_count": 87,
         "retweet_count": 9,
         "reply_count": 4,
         "quote_count": 1,
         "view_count": 11920,
         "bookmark_count": 6,
         "is_reply": true,
         "in_reply_to_username": "northwind_billing",
         "in_reply_to_tweet_id": "2116851177420881920",
         "is_quote_status": false,
         "conversation_id_str": "2116851177420881920",
         "entities": [],
         "user": {
           "id": "1371240448912351233",
           "username": "dana_ships_daily_x",
           "display_name": "Dana Okafor",
           "followers_count": 12650,
           "verified": true,
           "created_at": "2021-03-15T00:00:00Z"
         }
       }
     ],
     "next_cursor": "DAADDAABCgABHWD2c1tQkCsKAAIdYAk3gl1QYQ"
   }
   

   Ver resposta completa

4. Siga o cursor. Uma página traz até 20 menções, cada uma com o perfil completo do autor dentro de user. Envie next_cursor de volta 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 que ela 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.

Digite um handle e as palavras que as pessoas usam para a marca abaixo. O montador escreve a requisição /mentions em curl, Python e Node.js, além da consulta de busca que encontra posts que citam a marca sem marcação.

curl -X POST "https://api.sorsa.io/v3/mentions" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "northwind_billing", "order": "latest"}'

import requests

r = requests.post(
    "https://api.sorsa.io/v3/mentions",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={
        "query": "northwind_billing",
        "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/mentions", {
  method: "POST",
  headers: { ApiKey: "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "northwind_billing",
    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);

("northwind billing" OR northwnd OR url:northwind.io) -from:northwind_billing

#Filtre menções por curtidas, respostas e data

POST /mentions filtra do lado da Sorsa API, então uma requisição pede apenas as menções de que um trabalho precisa e percorre menos delas. Todo filtro fica no mesmo corpo JSON que o handle, e eles se combinam livremente:

• query

  O que faz

  O handle cujas menções você quer, sem o @

• order

  O que faz

  latest, mais novas primeiro (o padrão), ou popular, mais engajadas primeiro

• min_likes

  O que faz

  Mantém menções com pelo menos essa quantidade de curtidas

• min_replies

  O que faz

  Mantém menções com pelo menos essa quantidade de respostas

• min_retweets

  O que faz

  Mantém menções com pelo menos essa quantidade de reposts

• since_date

  O que faz

  Início da janela de datas, como YYYY-MM-DD

• until_date

  O que faz

  Fim da janela de datas, como YYYY-MM-DD

• next_cursor

  O que faz

  O cursor da última resposta, para a página seguinte

Quatro corpos cobrem o que a maioria das equipes envia. Cada um é um corpo de requisição completo para o comando curl acima:

# Support queue: every mention, newest first, no thresholds
{"query": "northwind_billing", "order": "latest"}

# PR and reputation: mentions that reached people
{"query": "northwind_billing", "order": "popular", "min_likes": 100}

# Campaign report: one month of mentions
{"query": "northwind_billing",
 "since_date": "2026-10-01", "until_date": "2026-10-31"}

# Competitor: what people tell a rival, with some traction
{"query": "ledgerly_founder_hq", "order": "popular", "min_retweets": 10}

Mantenha limites fora de um feed de suporte: um relato de bug com duas curtidas precisa de resposta mais cedo do que uma piada com quinhentas. Os limites pertencem a relatórios e alertas, em que um punhado de menções que viajaram importa mais do que toda resposta. Para colocar as menções de um concorrente ao lado dos seguidores e dos hábitos de postagem dele, veja o nosso guia de análise de concorrentes no Twitter.

#Colete todas as páginas e depois só as menções novas

Um backfill e um monitor são a mesma requisição com uma regra de parada diferente. Um backfill lê uma janela de datas até o cursor acabar; um monitor lê as menções mais novas e para na primeira que já guardou.

O backfill abaixo grava um mês de menções em um arquivo JSON Lines, uma menção por linha, conforme as páginas chegam. Um orçamento de páginas o detém, de modo que uma conta movimentada não consuma suas requisições sem limite.

import json
import requests

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


def mentions(handle, max_pages=100, **filters):
    body = {"query": handle, "order": "latest", **filters}
    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


with open("mentions.jsonl", "w", encoding="utf-8") as f:
    for t in mentions("northwind_billing",
                      since_date="2026-10-01",
                      until_date="2026-10-31"):
        f.write(json.dumps(t) + "\n")

import { appendFileSync, writeFileSync } from "node:fs";

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

async function* mentions(handle, filters = {}, maxPages = 100) {
  const body = { query: handle, order: "latest", ...filters };
  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 october = { since_date: "2026-10-01", until_date: "2026-10-31" };
writeFileSync("mentions.jsonl", "");
for await (const t of mentions("northwind_billing", october)) {
  appendFileSync("mentions.jsonl", JSON.stringify(t) + "\n");
}

Para manter um feed atualizado, rode a função abaixo em intervalos. Ela percorre as menções mais novas página a página e para no primeiro ID que já viu, então uma verificação que não encontra nada de novo custa uma única requisição. Os IDs de tweets crescem com o tempo, mas chegam como strings, então a comparação os transforma em inteiros.

from pathlib import Path

STATE = Path("last_mention_id.txt")


def new_mentions(handle):
    last = int(STATE.read_text()) if STATE.exists() else 0
    fresh = []
    for t in mentions(handle, max_pages=10):
        if int(t["id"]) <= last:
            break
        fresh.append(t)
    if fresh:
        STATE.write_text(fresh[0]["id"])
    return fresh

A primeira execução não tem ID guardado, então lê até 10 páginas e guarda a mais nova. Com que frequência rodá-la depois disso depende da rapidez com que alguém precisa responder: uma central de suporte verifica a cada minuto, um relatório semanal uma vez por dia.

Bom saber

Guarde o último ID fora do processo: em um arquivo, uma linha de banco de dados ou uma chave do Redis. Um monitor que reinicia sem ele ou avisa de novo sobre menções antigas ou pula tudo o que foi postado enquanto esteve fora do ar.

Para alertas no Slack ou por e-mail e agendas para muitas contas, o nosso guia de monitoramento do Twitter em tempo real monta o pipeline inteiro. Acompanhar o que um grupo de contas posta é um trabalho diferente de ler o que os outros dizem a elas. Uma Lista do X cobre até 5.000 contas em um único feed: veja o guia da API de Listas e Comunidades do X.

#Pegue as menções que nunca marcam você

POST /mentions devolve os posts que levam o @handle. As pessoas também escrevem sobre uma marca sem marcá-la: pelo nome, com um erro de digitação, com um link para o site dela ou citando um de seus posts. Cada um desses formatos tem o seu próprio endpoint na Sorsa API.

Para nomes, erros de grafia e links, envie uma consulta para POST /search-tweets (abre em uma nova aba) e deixe de fora os posts da própria marca:

("northwind billing" OR northwnd OR url:northwind.io) -from:northwind_billing

Um post que marca a marca e a nomeia volta dos dois endpoints, então use o ID do tweet como chave nos dois feeds e guarde uma única cópia. Leia cem resultados de uma consulta nova antes de agendá-la: um nome de marca que também é uma palavra do dia a dia precisa de mais exclusões, não de menos páginas.

Os quotes de um único post vêm de POST /quotes (abre em uma nova aba), com o texto do quote e o autor dele, quer o quote marque a marca ou não. As contas que repostaram um post vêm de POST /retweeters (abre em uma nova aba) como perfis. O nosso guia da API de busca do Twitter explica a sintaxe das consultas e o loop de busca, e a lista de operadores de busca do Twitter cobre todos os filtros que uma consulta pode levar.

#O endpoint oficial de menções, lado a lado

O GET /2/users/{id}/mentions da API oficial do X e o POST /mentions da Sorsa API devolvem os mesmos posts públicos. Eles diferem no que você envia, no que volta e no que custa. Sete critérios decidem um trabalho de menções: preço por 1.000, histórico, filtros, dados do autor, configuração, limite de requisições e o que acontece com a sua conta do X.

A tabela coloca os dois endpoints lado a lado, com os limites oficiais tirados da tabela de limites de requisições do X (abre em uma nova aba). A Sorsa API custa cerca de 71 vezes menos por 1.000 menções de qualquer conta, e 14 vezes menos que a tarifa oficial para ler as da sua própria.

• Entrada da conta

  Sorsa API

  O handle

  API oficial do X

  O ID numérico de usuário, depois de uma consulta

• Menções por requisição

  Sorsa API

  Até 20

  API oficial do X

  De 5 a 100

• Até onde no passado

  Sorsa API

  Qualquer janela de datas que você defina; anos atrás por /search-tweets

  API oficial do X

  As 800 mais recentes

• Filtros

  Sorsa API

  Curtidas, respostas, reposts, datas

  API oficial do X

  Datas e IDs de posts

• Perfil do autor

  Sorsa API

  Dentro de cada menção

  API oficial do X

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

• Limite de requisições

  Sorsa API

  20 requisições por segundo por chave

  API oficial do X

  450 requisições a cada 15 minutos por app

• Preço por 1.000 menções

  Sorsa API

  A partir de US$ 0,07

  API oficial do X

  US$ 5,00; US$ 1,00 para a sua própria conta

• Configuração

  Sorsa API

  Uma chave de API

  API oficial do X

  Conta de desenvolvedor, app, bearer token

• Sua conta do X

  Sorsa API

  Nunca usada

  API oficial do X

  Vinculada à conta de desenvolvedor

A Sorsa API é somente leitura por projeto, então nunca pede o seu login do X e a sua conta nunca corre risco. Para responder a menções por código, combine-a com a API oficial do X para as respostas: a leitura fica na Sorsa API, e a postagem passa pelo X.

#Quanto custam as menções por 1.000

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

Três detalhes mexem na conta oficial. As menções da sua própria conta, lidas pelo seu próprio app de desenvolvedor, contam como leituras próprias a US$ 0,001 por post. A partir de 22 de novembro de 2026, cada autor devolvido por expansions acrescenta US$ 0,010 (aviso do X de 23 de outubro (abre em uma nova aba)), então 1.000 menções de 1.000 pessoas diferentes chegam a US$ 15,00. E o pagamento por uso para em 3 milhões de leituras de posts por mês, depois do que o X vende apenas contratos Enterprise. Todas as tarifas oficiais estão no nosso detalhamento dos preços da API do X.

#Puxe suas primeiras menções hoje

As menções de uma conta estão a uma requisição de distância. Coloque o handle em POST /mentions, acrescente as curtidas, respostas, reposts ou datas que importam para você, e até 20 menções voltam com seus autores. A Sorsa API as devolve a partir de US$ 0,07 por 1.000, contra US$ 5,00 na API oficial do X, sem conta de desenvolvedor. Suas 100 requisições grátis cobrem as primeiras 2.000.

#Perguntas frequentes