Monitoramento de menções

/mentions retorna publicações que mencionam uma conta. Use para monitorar marcas, encaminhar pedidos de suporte, medir campanhas e acompanhar concorrentes. Os filtros de engajamento e data são parâmetros próprios no corpo da requisição. Cada página retorna até 20 publicações.

Veja código de produção, monitoramento em vários canais e análise competitiva no guia completo de menções, no blog.

Início rápido

curl -X POST https://api.sorsa.io/v3/mentions \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AppleSupport",
    "order": "latest",
    "min_likes": 10,
    "since_date": "2026-03-01"
  }'

Teste /mentions sem código no API Playground. Cada conta começa com 100 requisições gratuitas, sem cartão.

Referência do endpoint

POST https://api.sorsa.io/v3/mentions

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Nome de usuário sem @, como `"elonmusk"`.
`order`	string	Não	`"latest"` (padrão, recentes primeiro) ou `"popular"` (por engajamento).
`since_date`	string	Não	Data inicial em `YYYY-MM-DD`.
`until_date`	string	Não	Data final em `YYYY-MM-DD`.
`min_likes`	integer	Não	Mínimo de curtidas.
`min_retweets`	integer	Não	Mínimo de repostagens.
`min_replies`	integer	Não	Mínimo de respostas.
`next_cursor`	string	Não	Cursor da resposta anterior.

Cada chamada consome uma requisição, retornando uma ou vinte menções.

Resposta

{
  "tweets": [
    {
      "id": "2031847200012345678",
      "full_text": "@AppleSupport My iPhone keeps restarting after the latest update. Anyone else?",
      "created_at": "2026-03-08T14:22:31Z",
      "lang": "en",
      "likes_count": 47,
      "retweet_count": 12,
      "reply_count": 8,
      "quote_count": 2,
      "view_count": 15200,
      "is_reply": false,
      "is_quote_status": false,
      "user": {
        "id": "9876543210",
        "username": "frustrated_user",
        "display_name": "Alex",
        "followers_count": 1240,
        "verified": false
      }
    }
  ],
  "next_cursor": "DAABCgABGSmiaxkA..."
}

Cada menção inclui métricas completas e o perfil do autor em user, abreviado acima. As datas usam ISO 8601. Um next_cursor presente indica mais páginas; nulo ou ausente indica o fim. Veja paginação e formato de resposta.

/mentions ou /search-tweets?

Use /mentions para posts com marcação @brand, respostas e referências ao perfil. Os filtros min_likes, min_retweets, min_replies, since_date e until_date são parâmetros próprios.
Use /search-tweets para referências sem marcação, lógica booleana e filtros de mídia. A consulta "Nike" -from:Nike lang:en encontra o nome da marca no texto.

Para cobrir a marca, execute ambos e deduplique pelo ID da publicação.

Padrões comuns

Filtrar por engajamento

Selecione menções que já alcançaram uma audiência para painéis de reputação e relações públicas.

import requests

API_KEY = "YOUR_API_KEY"
URL = "https://api.sorsa.io/v3/mentions"

body = {"query": "nike", "order": "popular", "min_likes": 100}
resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)
resp.raise_for_status()
mentions = resp.json().get("tweets", [])

Capturar todas as menções para suporte

Remova filtros de engajamento e use ordem cronológica, incluindo menções sem interações.

body = {"query": "YourBrandSupport", "order": "latest", "since_date": "2026-05-10"}
resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)

Analisar uma campanha por período

Defina since_date e until_date e percorra next_cursor até o fim.

import time

def all_mentions(handle, since, until, max_pages=50):
    out, cursor = [], None
    for _ in range(max_pages):
        body = {"query": handle, "order": "latest", "since_date": since, "until_date": until}
        if cursor:
            body["next_cursor"] = cursor
        resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)
        resp.raise_for_status()
        data = resp.json()
        out.extend(data.get("tweets", []))
        cursor = data.get("next_cursor")
        if not cursor:
            break
        time.sleep(0.1)
    return out

Consultar novas menções periodicamente

Acompanhe o ID mais recente entre ciclos. Compare os IDs numericamente, pois são retornados como strings.

last_seen_id = None
while True:
    resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
                         json={"query": "yourbrand", "order": "latest"})
    resp.raise_for_status()
    tweets = resp.json().get("tweets", [])
    if tweets and last_seen_id is None:
        last_seen_id = max((t["id"] for t in tweets), key=int)
    elif tweets:
        new = [t for t in tweets if int(t["id"]) > int(last_seen_id)]
        # handle `new` mentions
        if new:
            last_seen_id = max((t["id"] for t in new), key=int)
    time.sleep(15)

Este exemplo consulta a primeira página e define uma referência inicial sem emitir resultados antigos. Em feeds movimentados, percorra o intervalo pendente antes de avançar o checkpoint. Mantenha uma sobreposição e deduplique IDs para lidar com resultados atrasados. Persista last_seen_id em disco ou Redis e trate erros transitórios com try/except e espera progressiva. Veja o padrão completo em monitoramento em tempo real.

Erros comuns

Filtro alto demais para suporte. Um relato de erro com 2 curtidas pode importar mais que um meme com 500. Use min_likes igual a 0 e encaminhe por palavras-chave.
Ler só uma página em contas movimentadas. Cada chamada retorna até 20 menções. Percorra todas as páginas e considere uma requisição por página no orçamento.
Tratar menções como cobertura completa. Inclua buscas por marca sem @ com /search-tweets.
Consultar contas pouco ativas com frequência excessiva. Ajuste ao volume: 15 segundos para marcas movimentadas, um ou dois minutos para contas menores. O limite é de 20 req/s; veja limites.
Não persistir o estado. Após reiniciar, o monitor pode repetir alertas antigos ou perder o intervalo sem checkpoint durável.

Próximos passos

Busca de publicações: menções sem marcação.
Operadores: mídia, localização e lógica booleana.
Monitoramento em tempo real: deduplicação e novas tentativas.
Dados históricos: períodos anteriores.
Referência do endpoint: especificação completa.

Primeiros passos

Conceitos básicos

Guias práticos

Suporte e recursos

Início rápido

Referência do endpoint

Resposta

/mentions ou /search-tweets?

Padrões comuns

Filtrar por engajamento

Capturar todas as menções para suporte

Analisar uma campanha por período

Consultar novas menções periodicamente

Erros comuns

Próximos passos

​Início rápido

​Referência do endpoint

​Resposta

​/mentions ou /search-tweets?

​Padrões comuns

​Filtrar por engajamento

​Capturar todas as menções para suporte

​Analisar uma campanha por período

​Consultar novas menções periodicamente

​Erros comuns

​Próximos passos

Início rápido

Referência do endpoint

Resposta

/mentions ou /search-tweets?

Padrões comuns

Filtrar por engajamento

Capturar todas as menções para suporte

Analisar uma campanha por período

Consultar novas menções periodicamente

Erros comuns

Próximos passos