Usar a API REST

A API REST da Searcherries dá a scripts, planilhas e plataformas de automação acesso de leitura aos dados que a Searcherries coletou para os seus projetos: métricas de visibilidade em IA, respostas de IA armazenadas com as respectivas avaliações, concorrentes, URLs e domínios citados, snapshots do Google Search Console e do Bing Webmaster Tools, snapshots de tráfego de IA do GA4 e um plano de ação priorizado. Ela retorna os mesmos conjuntos de dados que a conexão MCP, em JSON via HTTPS.

A API é somente leitura. Ela não pode editar projetos, alterar perguntas, excluir dados, gerenciar a cobrança nem disparar novas chamadas aos provedores de analytics. Cada resposta é montada com dados que a Searcherries já armazena, e cada uma informa quando esses dados foram obtidos. Leia sobre as atualizações de dados.

A API está disponível em todos os planos. Uma conta gratuita pode ler o próprio projeto, o desempenho de busca, o tráfego de IA e o plano de ação; os endpoints de visibilidade em IA (answers, competitors, citations) exigem acesso a um plano pago, e um teste grátis ativo e elegível também vale.

Para ler os mesmos dados em um terminal sem escrever requisições, use a ferramenta de linha de comando.

URL base e formato

Todos os endpoints ficam em:

https://app.searcherries.com/api/v1

As requisições usam GET com parâmetros na query string. As respostas são documentos JSON. Os booleanos da query string aceitam true, false, 1 e 0. Listas como include aceitam um valor separado por vírgulas.

A descrição legível por máquina de cada endpoint, parâmetro e resposta é um documento OpenAPI 3.1 em https://app.searcherries.com/openapi/v1.yaml. Importe-o em um cliente de API ou em uma plataforma de integração para ter os endpoints prontos para chamar.

Autenticação

A API usa os tokens de acesso pessoais da página MCP. Crie um token na aba Other clients (Outros clientes) do MCP e envie-o como token Bearer:

Authorization: Bearer YOUR_TOKEN

YOUR_TOKEN representa o valor que você gerou. Um token criado para um cliente MCP também funciona com a API, e um token revogado na página MCP deixa de funcionar em todos os lugares ao mesmo tempo. Uma conta pode ter até cinco tokens ativos; cada um expira na data mostrada na tabela.

Uma requisição sem um token válido recebe 401. Um token de uma conta gratuita recebe 403 com o código de erro paid_plan_required nos endpoints de visibilidade em IA (answers, competitors, citations); os demais endpoints respondem, com os blocos de IA marcados como upgrade_required.

Experimente

Liste os seus projetos:

curl -H "Authorization: Bearer YOUR_TOKEN" https://app.searcherries.com/api/v1/projects

A resposta contém o id numérico de cada projeto. Use-o para ler o resumo do projeto:

curl -H "Authorization: Bearer YOUR_TOKEN" https://app.searcherries.com/api/v1/projects/123

Substitua 123 pelo id do seu projeto. A referência de endpoints lista todos os endpoints e parâmetros.

Períodos

Os dados de visibilidade em IA (respostas, concorrentes, citações, as métricas do resumo) usam períodos de relatório ancorados na última verificação concluída: last_30_days (padrão), last_60_days, last_90_days, this_year e last_year. Quando um período não tem histórico suficiente, a API usa o período disponível mais próximo, e o objeto period da resposta informa qual foi usado.

As fontes conectadas (Google Search Console, Bing Webmaster Tools, GA4) são armazenadas como janelas móveis que terminam no dia da coleta: 30d, 90d e 365d. As respostas delas trazem period, fetched_at e is_stale. Quando uma fonte ou uma janela não tem dados armazenados, a resposta diz "available": false e explica o motivo em reason.

Paginação

Os conjuntos de dados que retornam linhas incluem um objeto pagination:

{
  "offset": 0,
  "limit": 25,
  "returned": 25,
  "total": 112,
  "has_more": true
}

Peça a próxima página com um offset maior enquanto has_more for true. A página padrão tem 25 linhas e o máximo é 100 (50 para concorrentes). As listas das fontes conectadas são a amostra armazenada dos principais itens e não incluem todas as linhas.

Limites de requisições

Cada conta pode fazer 30 requisições por minuto no plano Free, 60 no Starter e 120 no Pro. Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Quando a cota acaba, a API responde 429 com um cabeçalho Retry-After e o mesmo número de segundos em retry_after. Espere e tente de novo; não repita a requisição em um loop sem pausa.

Erros

Todo erro é um objeto JSON com uma única chave error:

{
  "error": {
    "code": "validation_failed",
    "message": "The request parameters are invalid.",
    "status": 422,
    "errors": {
      "period": ["The selected period is invalid."]
    }
  }
}

Status	Código	Significado
401	`unauthenticated`	Token ausente, expirado ou revogado.
403	`insufficient_scope`	O token não pode ler a API. Crie um novo token na página MCP.
403	`paid_plan_required`	A conta não tem acesso a um plano pago para este endpoint (`answers`, `competitors`, `citations`). `plans_url` aponta para a página de planos.
404	`not_found`	O id do projeto não existe ou pertence a outra conta.
422	`validation_failed`	Um parâmetro é inválido; `errors` lista as mensagens por parâmetro.
429	`rate_limited`	A cota por minuto acabou; `retry_after` informa quanto tempo esperar.
500	`server_error`	Algo falhou do lado da Searcherries. Tente de novo mais tarde ou fale com o suporte.

Privacidade e acesso

Um token lê os dados da conta da Searcherries que o criou e nada mais. Mantenha os tokens fora de repositórios públicos, documentos compartilhados e capturas de tela; se um token vazar, revogue-o na página MCP e crie outro para substituí-lo.

A API entrega dados armazenados à ferramenta que você conectar. Essa ferramenta pode ter assinatura, cobranças por uso e configurações de tratamento de dados próprias. Conecte apenas as ferramentas que você pretende usar com os dados do seu projeto.