API pública (V2) - AppSignal Documentation

A API pública (V2) é uma API REST para ler dados brutos da aplicação: métricas, traces, logs, métricas de Kubernetes e estatísticas de deploy. Ela complementa a API GraphQL, que gerencia modelos como apps, incidentes, dashboards e alertas. Como regra geral, use a API REST para ler dados e a API GraphQL para gerenciar configuração.

Se você está construindo um agente ou assistente de IA, o AppSignal MCP expõe esses dados diretamente aos agentes — você pode não precisar chamar esta API por conta própria.

URL base

Todos os endpoints são servidos sob /api/v2 no domínio appsignal.com:

https://appsignal.com/api/v2

Autenticação

As requisições são autenticadas com seu token pessoal de API, passado como bearer token ou como parâmetro de query. Você pode encontrar seu token na tela de configurações pessoais.

curl -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  https://appsignal.com/api/v2/metrics/names/YOUR-SITE-ID

curl "https://appsignal.com/api/v2/metrics/names/YOUR-SITE-ID?token=YOUR-PERSONAL-API-TOKEN"

Seu token dá acesso aos mesmos sites e organizações que você vê na AppSignal. A maioria das requisições tem escopo de um único site_id; os endpoints de tracing usam um array site_ids para que possam buscar em vários sites. A API verifica se seu token tem acesso a todos os sites solicitados antes de retornar dados. Para verificar o próprio token, chame GET /api/v2/auth. Seu site_id é o ID na URL do seu app: https://appsignal.com/<organization>/sites/<SITE_ID>. Para queries de log você também precisa de um ID de fonte de log — veja encontrando seus IDs de site e fonte.

Verificar um token

GET /api/v2/auth

Retorna um objeto JSON com uma message confirmando o ID do usuário autenticado.

Requisições e respostas

A maioria dos endpoints usa POST com um corpo JSON e retorna JSON. Consultas somente leitura (como listar nomes de métricas) usam GET com parâmetros de path. Defina Content-Type: application/json em requisições com corpo. Horários são strings ISO 8601. A maioria dos corpos de query recebe um intervalo de tempo from e to mais um site_id ou, para endpoints de tracing, um array site_ids. Para uma referência completa, gerada automaticamente, de cada endpoint, requisição e tipo de resposta, consulte a referência da API REST.

Respostas de erro

Qualquer endpoint pode retornar estas respostas não-2xx:

Status	Significado	Corpo
`401`	Token ausente ou inválido	`{ "error": "Unauthorized" }`
`404`	Rota ou recurso não encontrado	`{ "error": "Not found" }`
`422`	Requisição parseada mas não pode ser processada	Envelope de erro (veja a seção a seguir)
`500`	Falha não tratada no servidor	`{ "error": "<message>" }`

Envelope 422

Toda resposta 422 usa o mesmo envelope, para que você possa tratá-las em um único lugar:

{
  "error": "<stable_slug>",
  "message": "<human-readable message>",
  "details": {}
}

error: um slug estável, legível por máquina. Faça branching com base nele em seu código.
message: uma mensagem legível por humanos, segura para exibir.
details: um objeto opcional cujo formato depende de error.

Um slug que você pode encontrar é legacy_log_query_syntax, retornado quando uma query de logs usa a sintaxe legada attributes.<name>_<type>. Veja consultando logs para a linguagem de query atual.

Endpoints

Métricas

Método	Path	Descrição
`POST`	`/api/v2/metrics/timeseries`	Consultar dados de métrica como timeseries
`POST`	`/api/v2/metrics/list`	Consultar dados agregados de métrica como uma lista com agrupamento
`GET`	`/api/v2/metrics/names/{site_id}`	Listar todos os nomes de métrica de um site
`GET`	`/api/v2/metrics/type_and_tags/{site_id}/{metric_name}`	Obter o tipo e as tags disponíveis de uma métrica

Consulte a referência de métricas.

Tracing

Método	Path	Descrição
`POST`	`/api/v2/tracing/locator`	Localizar um trace entre sites por trace ID
`POST`	`/api/v2/tracing/trace`	Obter todos os spans de um trace
`POST`	`/api/v2/tracing/trace/performance`	Obter spans de um trace de performance
`POST`	`/api/v2/tracing/trace/error`	Obter spans de um trace de erro
`POST`	`/api/v2/tracing/traces/performance`	Listar traces de performance
`POST`	`/api/v2/tracing/traces/errors`	Listar traces de erro
`POST`	`/api/v2/tracing/actions`	Listar ações de performance com métricas agregadas
`POST`	`/api/v2/tracing/action_edges`	Listar arestas upstream e downstream de uma ação
`POST`	`/api/v2/tracing/site_edges`	Listar arestas de dependência de serviço para um site
`POST`	`/api/v2/tracing/slow_events`	Listar eventos lentos com estatísticas agregadas
`POST`	`/api/v2/tracing/slow_events/actions`	Listar ações relacionadas a um evento lento

Consulte a referência de tracing.

Logs

Método	Path	Descrição
`POST`	`/api/v2/logs/lines`	Buscar linhas de log

Consulte a referência de logs.

Kubernetes

Método	Path	Descrição
`POST`	`/api/v2/kubernetes/nodes`	Consultar métricas de node
`POST`	`/api/v2/kubernetes/pods`	Consultar métricas de pod
`POST`	`/api/v2/kubernetes/pods/overview`	Consultar visão geral de pods com labels e status

Consulte a referência de Kubernetes.

Deploys

Método	Path	Descrição
`POST`	`/api/v2/deploys/stats`	Obter estatísticas de deploy de uma revisão

Consulte a referência de deploys.

Check-ins

Método	Path	Descrição
`POST`	`/api/v2/check_ins/test_cron`	Testar e validar uma expressão de agendamento cron

Consulte a referência de check-ins.

Visuais salvos

Método	Path	Descrição
`GET`	`/api/v2/saved_visuals/{id}`	Recuperar um visual salvo como JSON
`GET`	`/api/v2/saved_visuals/{id}/csv`	Baixar um visual salvo como CSV

Os endpoints de visual salvo não exigem autenticação. Consulte a referência de visuais salvos.

Sistema

Método	Path	Descrição
`GET`	`/api/v2/auth`	Verificar se um token é válido

​URL base

​Autenticação

​Verificar um token

​Requisições e respostas

​Respostas de erro

​Envelope 422

​Endpoints

​Métricas

​Tracing

​Logs

​Kubernetes

​Deploys

​Check-ins

​Visuais salvos

​Sistema

URL base

Autenticação

Verificar um token

Requisições e respostas

Respostas de erro

Envelope 422

Endpoints

Métricas

Tracing

Logs

Kubernetes

Deploys

Check-ins

Visuais salvos

Sistema