Métricas de Rede

As métricas de rede ajudam a investigar tráfego HTTP, códigos de status, rotas mais acessadas, latência, user agents e IPs de origem. Estes endpoints estão disponíveis para projetos HTTP em planos com acesso a métricas.

Permissões necessárias

Endpoints	Scope mínimo
`summary`, `status-codes`, `routes` e `user-agents`	`project.metrics.read` em `project:<project-id>`
`request-events` e `source-ips`	`project.network.visitors.read` em `project:<project-id>`

request-events e source-ips retornam o IP de origem e o user agent de cada visitante, por isso exigem uma permissão própria. project.metrics.read não dá acesso a eles: a consulta responde 403, sem versão mascarada. owner tem acesso completo; assistant, member e API Keys da organização precisam do scope correspondente, e project.network.visitors.read não faz parte do modelo inicial de assistant. Conexões de assistentes de IA via MCP consultam apenas os endpoints agregados.

Em ambientes de Preview, a permissão é verificada no projeto principal do Preview.

Headers

Header	Obrigatório	Descrição
`x-api-key` ou `Authorization`	Sim	API Key da organização ou token de usuário
`x-organization-id`	Com token de usuário	Organização ativa do projeto. Dispensável com API Key da organização

Endpoints

Endpoint	Uso principal
`GET /v1/project/:id/metrics/network/summary`	Visão agregada de requests, bytes, latência e classes de status
`GET /v1/project/:id/metrics/network/status-codes`	Agrupamento por código HTTP
`GET /v1/project/:id/metrics/network/routes`	Rotas mais acessadas e status por rota
`GET /v1/project/:id/metrics/network/user-agents`	User agents mais frequentes
`GET /v1/project/:id/metrics/network/request-events`	Eventos individuais de requisição
`GET /v1/project/:id/metrics/network/source-ips`	IPs de origem com maior volume

Parâmetros de Path

Parâmetro	Tipo	Descrição
`id`	string	ID do projeto

Filtros de Query

Parâmetro	Tipo	Descrição
`range_seconds`	number	Janela relativa. Valores aceitos: `300`, `3600`, `21600`, `86400`, `604800`
`from`	string	Data inicial em formato ISO 8601. Precisa ser anterior ou igual a `to`
`to`	string	Data final em formato ISO 8601
`status_code`	string	Código HTTP específico, como `500`
`status_class`	string	Classe HTTP: `2xx`, `3xx`, `4xx` ou `5xx`
`source_ip`	string	IP de origem para filtrar eventos
`path`	string	Caminho HTTP para filtrar eventos
`page`	number	Página da paginação. Padrão: `1`, máximo: `10000`
`limit`	number	Itens por página. Padrão: `5`, máximo: `50`

Use range_seconds para dashboards simples. Use from e to quando precisar comparar uma janela específica de incidente.

Sem range_seconds, from ou to, a consulta usa as últimas 24 horas. A janela máxima é de 7 dias contados a partir de to: um from mais antigo é ajustado para esse limite.

Summary

GET /v1/project/:id/metrics/network/summary

{
  "status": "success",
  "message": "get network analytics summary with success",
  "data": {
    "project_id": "507f1f77bcf86cd799439011",
    "window": {
      "from": "2026-05-23T13:00:00.000Z",
      "to": "2026-05-23T14:00:00.000Z",
      "seconds": 3600
    },
    "summary": {
      "requests": 1200,
      "bytes_received": 420000,
      "bytes_sent": 1800000,
      "avg_latency_ms": 42,
      "p95_latency_ms": 120
    },
    "status_classes": {
      "2xx": 1160,
      "3xx": 20,
      "4xx": 15,
      "5xx": 5
    }
  }
}

Listas Paginadas

Os endpoints status-codes, routes, user-agents, request-events e source-ips retornam data e pagination.

{
  "status": "success",
  "message": "get network analytics status codes with success",
  "data": {
    "data": [
      {
        "status_code": "200",
        "requests": 1160,
        "user_agents": {
          "Mozilla/5.0": 900,
          "curl/8.0": 260
        },
        "routes": {
          "GET /": 800,
          "GET /health": 360
        },
        "bytes_received": 390000,
        "bytes_sent": 1600000,
        "avg_latency_ms": 39,
        "p95_latency_ms": 110
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 5,
      "total": 1,
      "total_pages": 1
    }
  }
}

Eventos de requisição

Cada item de request-events representa uma requisição recebida pela aplicação:

{
  "status": "success",
  "message": "get network analytics request events with success",
  "data": {
    "data": [
      {
        "timestamp": "2026-05-23T13:58:12.000Z",
        "source_ip": "203.0.113.10",
        "method": "GET",
        "path": "/",
        "status_code": "200",
        "bytes_received": 320,
        "bytes_sent": 1540,
        "user_agent": "Mozilla/5.0",
        "latency_ms": 38
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 5,
      "total": 1,
      "total_pages": 1
    }
  }
}

source-ips retorna itens com source_ip e requests, ordenados pelo volume de requisições.

Exemplos

Resumo da última hora

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/metrics/network/summary?range_seconds=3600" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id"

Rotas com erros 5xx

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/metrics/network/routes?status_class=5xx&limit=10" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id"

Eventos de um IP específico

Exige project.network.visitors.read.

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/metrics/network/request-events?source_ip=203.0.113.10" \
  -H "x-api-key: sua-api-key" \
  -H "x-organization-id: sua-organization-id"

Python

import requests

API_KEY = "sua-api-key"
ORGANIZATION_ID = "sua-organization-id"
PROJECT_ID = "507f1f77bcf86cd799439011"

headers = {"x-api-key": API_KEY, "x-organization-id": ORGANIZATION_ID}

summary = requests.get(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/metrics/network/summary",
    params={"range_seconds": 3600},
    headers=headers
).json()

print(summary)

Erros Comuns

Código	Motivo provável	Como resolver
`400`	Parâmetro inválido, como `range_seconds` fora da lista, data fora do formato ISO 8601 ou `from` posterior a `to`	Revise os filtros de query
`402`	Plano não permite acesso a métricas	Faça upgrade para um plano com métricas habilitadas
`403`	Organização ou permissão inválida (`insufficient organization permission`)	Confirme `x-organization-id` e o scope exigido pelo endpoint; `request-events` e `source-ips` exigem `project.network.visitors.read`
`422`	Projeto não é HTTP (`code: "PROJECT_OPERATION_NOT_SUPPORTED"`)	Use métricas de banco em Métricas e Logs
`404`	Projeto não encontrado	Confira `Project ID`, API Key e organização

Próximos Passos

Use Métricas e Logs para CPU, memória e logs.
Consulte Instâncias para relacionar tráfego com réplicas.
Veja Histórico de Deployments ao investigar incidentes após deploy.

Nessa página