> ## Documentation Index > Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://api.sorsa.io/blog/twitter-mentions-api), no blog. ## Início rápido ```bash theme={null} 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](https://api.sorsa.io/playground). Cada conta começa com 100 requisições gratuitas, sem cartão. ## Referência do endpoint ```text theme={null} 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 ```json theme={null} { "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](https://docs.sorsa.io/pt-BR/pagination) e [formato de resposta](https://docs.sorsa.io/pt-BR/response-format). ## /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`](https://docs.sorsa.io/pt-BR/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. ```python theme={null} 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. ```python theme={null} 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. ```python theme={null} 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. ```python theme={null} 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](https://docs.sorsa.io/pt-BR/real-time-monitoring). ## 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](https://docs.sorsa.io/pt-BR/rate-limits). * **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](https://docs.sorsa.io/pt-BR/search-tweets): menções sem marcação. * [Operadores](https://docs.sorsa.io/pt-BR/search-operators): mídia, localização e lógica booleana. * [Monitoramento em tempo real](https://docs.sorsa.io/pt-BR/real-time-monitoring): deduplicação e novas tentativas. * [Dados históricos](https://docs.sorsa.io/pt-BR/historical-data): períodos anteriores. * [Referência do endpoint](https://docs.sorsa.io/pt-br/api-reference/busca/buscar-men%C3%A7%C3%B5es): especificação completa.