Tráfego da aplicação

GET

apps

{id}

analytics

curl -G "https://api.vertracloud.app/v1/apps/app-abc123def456/analytics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "start=2026-11-02T18:00:00Z" \
  --data-urlencode "end=2026-11-03T18:00:00Z" \
  --data-urlencode "compare=true" \
  --data-urlencode "country=BR" \
  --data-urlencode "status=2xx" \
  --data-urlencode "path=/api" \
  --data-urlencode "breakdowns=country,path,referer" \
  --data-urlencode "limit=5"

{
  "response": {
    "start": "2026-11-02T18:00:00Z",
    "end": "2026-11-03T18:00:00Z",
    "hosts": [
      "my-app.vertraweb.app",
      "www.example.com"
    ],
    "web_published": true,
    "sampled": false,
    "stale": false,
    "generated_at": "2026-11-03T18:01:12Z",
    "history_days": 7,
    "interval": "1h",
    "summary": {
      "requests": 18420,
      "visits": 6310,
      "bytes": 412884113,
      "errors_4xx": 214,
      "errors_5xx": 9,
      "error_rate_4xx": 0.0116,
      "error_rate_5xx": 0.0005,
      "edge_time_p95_ms": 412
    },
    "series": [
      {
        "time": "2026-11-02T18:00:00Z",
        "requests": 702,
        "visits": 240,
        "bytes": 15331004,
        "errors_4xx": 8,
        "errors_5xx": 0
      },
      {
        "time": "2026-11-02T19:00:00Z",
        "requests": 731,
        "visits": 251,
        "bytes": 16120987,
        "errors_4xx": 11,
        "errors_5xx": 1
      }
    ],
    "previous": {
      "start": "2026-11-01T18:00:00Z",
      "end": "2026-11-02T18:00:00Z",
      "summary": {
        "requests": 16990,
        "visits": 5802,
        "bytes": 380112007,
        "errors_4xx": 190,
        "errors_5xx": 4,
        "error_rate_4xx": 0.0112,
        "error_rate_5xx": 0.0002,
        "edge_time_p95_ms": 455
      },
      "series": [
        {
          "time": "2026-11-01T18:00:00Z",
          "requests": 650,
          "visits": 222,
          "bytes": 14100222,
          "errors_4xx": 7,
          "errors_5xx": 0
        }
      ]
    },
    "breakdowns": {
      "country": [
        {
          "value": "BR",
          "label": null,
          "requests": 14210,
          "visits": 4902,
          "bytes": 318400221
        },
        {
          "value": "US",
          "label": null,
          "requests": 2105,
          "visits": 760,
          "bytes": 48112003
        },
        {
          "value": "PT",
          "label": null,
          "requests": 611,
          "visits": 204,
          "bytes": 13920110
        }
      ],
      "path": [
        {
          "value": "/",
          "label": null,
          "requests": 5210,
          "visits": 4100,
          "bytes": 90211003
        },
        {
          "value": "/pricing",
          "label": null,
          "requests": 1902,
          "visits": 1180,
          "bytes": 41230991
        }
      ],
      "referer": [
        {
          "value": "(none)",
          "label": null,
          "requests": 9120,
          "visits": 3300,
          "bytes": 201004112
        },
        {
          "value": "google.com",
          "label": null,
          "requests": 4410,
          "visits": 1890,
          "bytes": 98114003
        }
      ],
      "asn": [
        {
          "value": "28573",
          "label": "CLARO S.A.",
          "requests": 3300,
          "visits": 1100,
          "bytes": 70112008
        }
      ],
      "cache_status": [
        {
          "value": "hit",
          "label": null,
          "requests": 13011,
          "visits": 0,
          "bytes": 301100001
        },
        {
          "value": "dynamic",
          "label": null,
          "requests": 4100,
          "visits": 0,
          "bytes": 90113002
        }
      ]
    }
  }
}

Retorna o tráfego do site de uma aplicação: totais, uma série no tempo e os valores mais frequentes de cada dimensão (países, rotas, dispositivos, navegadores, referers…). Todo filtro vale para todas as partes da resposta, então uma chamada dá os números por trás de um clique na sub-aba Tráfego. São os mesmos dados de Tráfego e filtros, do Resumo e de Comparar.

string

obrigatório

O ID da aplicação. Se ela pertencer a um workspace, informe o ID dele no query parameter workspace_id.

string

Se a aplicação pertencer a um workspace, o ID do workspace. Obrigatório para membros do workspace que agem sobre uma aplicação que não lhes pertence.

string

Início da janela (ISO 8601). Padrão: 24 horas antes de end.

string

Fim da janela (ISO 8601). Padrão: agora. Não pode estar no futuro.

boolean

padrão:"false"

Envia também o período anterior, do mesmo tamanho e logo antes da janela, em previous. Padrão false.

string

Início do período a comparar (ISO 8601). O período comparado tem o mesmo tamanho da janela (end menos start) e começa aqui; previous.start e previous.end na resposta mostram qual foi. Implica compare=true e não pode ser enviado com compare=false. Sem ele, compare=true compara com o período logo antes da janela.

string

Dimensões separadas por vírgula para detalhar, como country,path. Omitido: todos os recortes. Vazio (breakdowns=): nenhum, só o resumo e a série, com resposta mais rápida. Nome desconhecido: VALIDATION_ERROR. As dimensões estão listadas em Filtros.

integer

padrão:"10"

Entradas por breakdown, de 1 a 25. Padrão 10.

A janela tem no máximo 30 dias e não pode começar antes do histórico do plano (7 ou 30 dias, veja Planos e limites).

Filtros

Cada dimensão abaixo também é um filtro, e todos podem ser combinados: cada um restringe todas as partes da resposta. Cada filtro recebe um valor, exatamente como aparece numa entrada de breakdown ou numa requisição do log, então um valor lido numa resposta pode ser enviado de volta sem mudar. Envie (none) para manter só as requisições que não têm nada na dimensão.

string

País do visitante, ISO 3166-1 alfa-2 (BR).

string

Código IATA da localização de borda que respondeu (GRU).

string

Hostname que o visitante pediu: o subdomínio da aplicação ou um dos seus domínios. Só são aceitos hosts da aplicação.

string

Caminho da requisição, sem a query string. É um prefixo: /api casa com /api, /api/users e /apix.

string

Método HTTP (GET, POST…).

string

Status HTTP que o visitante recebeu (404), ou uma classe: 2xx, 3xx, 4xx ou 5xx.

string

Versão do HTTP: HTTP/1.1, HTTP/2 ou HTTP/3.

string

Tipo de dispositivo: desktop, mobile ou tablet.

string

Sistema operacional do visitante (Windows, iOS…).

string

Navegador do visitante (Chrome, Safari…).

string

Host da página que levou à requisição (google.com). (none) é uma visita direta, sem referer.

string

Número do sistema autônomo da rede do visitante (28573).

string

Endereço IP do visitante.

string

Tipo de conteúdo respondido (html, json, css, js, png…).

string

Se a borda respondeu do cache: hit, miss, dynamic, bypass, expired, revalidated…

string

Categoria de um bot verificado (Search Engine Crawler…). (none) é um visitante que não é um bot verificado.

Resposta

object

Mostrar Toggle object

string

Início da janela realmente lida (ISO 8601). Pode ser arredondado em relação ao que você enviou.

string

Fim da janela realmente lida (ISO 8601).

string[]

Hostnames que foram lidos: o subdomínio da aplicação e seus domínios ativos.

boolean

false quando a aplicação não tem site publicado. A resposta é então um estado vazio, não um erro: hosts vem vazio e os dados também.

boolean

true quando o tráfego é alto o bastante para que os números sejam estimados a partir de uma amostra.

boolean

true quando os dados mais recentes não puderam ser lidos e esta é uma resposta anterior. Veja generated_at.

string

Quando os dados foram lidos (ISO 8601).

integer

Quantos dias para trás o plano do dono da aplicação consegue ler.

string

Tamanho de cada ponto de series: 1m, 5m, 15m ou 1h. A API escolhe pelo tamanho da janela: quanto menor a janela, mais finos os pontos.

object | null

Totais da janela. null quando não houve requisição na janela.

object[]

Pontos da série no tempo; time é o início de cada ponto.

object | null

O período anterior, só com compare=true; caso contrário null. Tem start, end, um summary (null quando não houve requisição nele) e uma series com o mesmo interval e o mesmo número de pontos da atual, na mesma ordem.

object

Entradas mais frequentes de cada dimensão, maior requests primeiro: só as dimensões pedidas em breakdowns, ou todas quando omitido. O filtro enviado vale para todas.

Mostrar Toggle entry

string

Valor da dimensão; envie-o como o filtro de mesmo nome. (none) significa que a requisição não tinha valor.

string | null

Nome legível quando value é um código (o nome da rede de um asn); null caso contrário.

integer

Requisições com este valor.

integer

Visitas a páginas com este valor.

integer

Bytes enviados aos visitantes.

Campos de summary, e dos mesmos totais em previous.summary:

integer

Requisições respondidas.

integer

Visitas a páginas: requisições que iniciam uma visita (uma página aberta direto ou vinda de outro site).

integer

Bytes enviados aos visitantes.

integer

Requisições respondidas com status 4xx.

integer

Requisições respondidas com status 5xx.

number

errors_4xx / requests, de 0 a 1.

number

errors_5xx / requests, de 0 a 1.

number

Percentil 95 do tempo de borda (quanto o visitante esperou pelo primeiro byte), em milissegundos. É o único número de velocidade que todos os planos recebem.

Campos de cada ponto de series (e de previous.series): time, requests, visits, bytes, errors_4xx e errors_5xx, com o mesmo significado de summary.

{
  "response": {
    "start": "2026-11-02T18:00:00Z",
    "end": "2026-11-03T18:00:00Z",
    "hosts": [
      "my-app.vertraweb.app",
      "www.example.com"
    ],
    "web_published": true,
    "sampled": false,
    "stale": false,
    "generated_at": "2026-11-03T18:01:12Z",
    "history_days": 7,
    "interval": "1h",
    "summary": {
      "requests": 18420,
      "visits": 6310,
      "bytes": 412884113,
      "errors_4xx": 214,
      "errors_5xx": 9,
      "error_rate_4xx": 0.0116,
      "error_rate_5xx": 0.0005,
      "edge_time_p95_ms": 412
    },
    "series": [
      {
        "time": "2026-11-02T18:00:00Z",
        "requests": 702,
        "visits": 240,
        "bytes": 15331004,
        "errors_4xx": 8,
        "errors_5xx": 0
      },
      {
        "time": "2026-11-02T19:00:00Z",
        "requests": 731,
        "visits": 251,
        "bytes": 16120987,
        "errors_4xx": 11,
        "errors_5xx": 1
      }
    ],
    "previous": {
      "start": "2026-11-01T18:00:00Z",
      "end": "2026-11-02T18:00:00Z",
      "summary": {
        "requests": 16990,
        "visits": 5802,
        "bytes": 380112007,
        "errors_4xx": 190,
        "errors_5xx": 4,
        "error_rate_4xx": 0.0112,
        "error_rate_5xx": 0.0002,
        "edge_time_p95_ms": 455
      },
      "series": [
        {
          "time": "2026-11-01T18:00:00Z",
          "requests": 650,
          "visits": 222,
          "bytes": 14100222,
          "errors_4xx": 7,
          "errors_5xx": 0
        }
      ]
    },
    "breakdowns": {
      "country": [
        {
          "value": "BR",
          "label": null,
          "requests": 14210,
          "visits": 4902,
          "bytes": 318400221
        },
        {
          "value": "US",
          "label": null,
          "requests": 2105,
          "visits": 760,
          "bytes": 48112003
        },
        {
          "value": "PT",
          "label": null,
          "requests": 611,
          "visits": 204,
          "bytes": 13920110
        }
      ],
      "path": [
        {
          "value": "/",
          "label": null,
          "requests": 5210,
          "visits": 4100,
          "bytes": 90211003
        },
        {
          "value": "/pricing",
          "label": null,
          "requests": 1902,
          "visits": 1180,
          "bytes": 41230991
        }
      ],
      "referer": [
        {
          "value": "(none)",
          "label": null,
          "requests": 9120,
          "visits": 3300,
          "bytes": 201004112
        },
        {
          "value": "google.com",
          "label": null,
          "requests": 4410,
          "visits": 1890,
          "bytes": 98114003
        }
      ],
      "asn": [
        {
          "value": "28573",
          "label": "CLARO S.A.",
          "requests": 3300,
          "visits": 1100,
          "bytes": 70112008
        }
      ],
      "cache_status": [
        {
          "value": "hit",
          "label": null,
          "requests": 13011,
          "visits": 0,
          "bytes": 301100001
        },
        {
          "value": "dynamic",
          "label": null,
          "requests": 4100,
          "visits": 0,
          "bytes": 90113002
        }
      ]
    }
  }
}

curl -G "https://api.vertracloud.app/v1/apps/app-abc123def456/analytics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "start=2026-11-02T18:00:00Z" \
  --data-urlencode "end=2026-11-03T18:00:00Z" \
  --data-urlencode "compare=true" \
  --data-urlencode "country=BR" \
  --data-urlencode "status=2xx" \
  --data-urlencode "path=/api" \
  --data-urlencode "breakdowns=country,path,referer" \
  --data-urlencode "limit=5"

Observações

Exige o escopo apps:read quando chamada com uma chave de API. Membros de workspace precisam de permissão para ler a aplicação.
Disponível em todos os planos. Uma conta sem plano ativo recebe PLAN_REQUIRED.
Amostragem. Com tráfego alto os números são estimados a partir de uma amostra e sampled vem true. Veja Amostragem e atraso.
Atraso. Os dados se atualizam a cada cerca de 5 minutos, então as requisições mais novas podem levar alguns minutos para aparecer. Se os dados mais recentes não puderem ser lidos agora, uma resposta anterior pode voltar com stale: true (veja generated_at); caso contrário, a chamada falha com ANALYTICS_BUSY.
Privacidade. A Vertra Cloud não guarda nada sobre os visitantes; guarda apenas totais por app (contagens, visitas, bytes, taxas de erro e tempos de resposta) por até 31 dias, apagados com o app. Nenhum IP, caminho, query string ou user agent é guardado. ip e query voltam sem máscara; mascarar é uma escolha do cliente que os exibe. Veja Privacidade.

Respostas de erro

Status	Código	Quando
401	`AUTH_TOKEN_MISSING` / `API_KEY_INVALID` / `SESSION_REVOKED`	O header `Authorization` está ausente, a chave de API é inválida ou a sessão do painel foi revogada.
403	`API_KEY_IP_DENIED` / `API_KEY_SCOPE_DENIED`	A chave de API é usada de um IP fora da sua lista de permitidos, ou não tem o escopo `apps:read`.
403	`ACCESS_DENIED`	A aplicação pertence a outra conta, ou você não tem a permissão de workspace para lê-la.
403	`PLAN_REQUIRED`	A conta não tem plano ativo.
404	`APP_NOT_FOUND`	A aplicação não existe.
400	`VALIDATION_ERROR`	Um parâmetro falhou na validação, como `limit` fora do intervalo, `cursor` inválido ou data `start`/`end` malformada; `details.path` nomeia o campo. Também quando `compare_start` é malformado ou vem com `compare=false`.
400	`INVALID_RANGE`	`start` é posterior a `end`, `end` está no futuro ou a janela passa de 30 dias. Também quando o período que começa em `compare_start` termina depois de `start`, o que sobreporia a janela.
400	`ANALYTICS_RANGE_EXCEEDS_PLAN`	`start` é anterior ao que o plano consegue ler. `details.history_days` traz o limite em dias e `details.earliest` o `start` mais antigo aceito agora. Também quando `compare_start` é anterior ao que o plano consegue ler.
429	`RATE_LIMIT_EXCEEDED`	Muitas consultas seguidas. `details.retry_after` informa a espera em segundos; o header `Retry-After` vem sempre junto.
503	`ANALYTICS_BUSY`	Momento de alta demanda e sem resposta recente disponível para a consulta. Espere `details.retry_after` segundos e tente de novo.

Última modificação em 3 de novembro de 2026

curl -G "https://api.vertracloud.app/v1/apps/app-abc123def456/analytics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "start=2026-11-02T18:00:00Z" \
  --data-urlencode "end=2026-11-03T18:00:00Z" \
  --data-urlencode "compare=true" \
  --data-urlencode "country=BR" \
  --data-urlencode "status=2xx" \
  --data-urlencode "path=/api" \
  --data-urlencode "breakdowns=country,path,referer" \
  --data-urlencode "limit=5"

{
  "response": {
    "start": "2026-11-02T18:00:00Z",
    "end": "2026-11-03T18:00:00Z",
    "hosts": [
      "my-app.vertraweb.app",
      "www.example.com"
    ],
    "web_published": true,
    "sampled": false,
    "stale": false,
    "generated_at": "2026-11-03T18:01:12Z",
    "history_days": 7,
    "interval": "1h",
    "summary": {
      "requests": 18420,
      "visits": 6310,
      "bytes": 412884113,
      "errors_4xx": 214,
      "errors_5xx": 9,
      "error_rate_4xx": 0.0116,
      "error_rate_5xx": 0.0005,
      "edge_time_p95_ms": 412
    },
    "series": [
      {
        "time": "2026-11-02T18:00:00Z",
        "requests": 702,
        "visits": 240,
        "bytes": 15331004,
        "errors_4xx": 8,
        "errors_5xx": 0
      },
      {
        "time": "2026-11-02T19:00:00Z",
        "requests": 731,
        "visits": 251,
        "bytes": 16120987,
        "errors_4xx": 11,
        "errors_5xx": 1
      }
    ],
    "previous": {
      "start": "2026-11-01T18:00:00Z",
      "end": "2026-11-02T18:00:00Z",
      "summary": {
        "requests": 16990,
        "visits": 5802,
        "bytes": 380112007,
        "errors_4xx": 190,
        "errors_5xx": 4,
        "error_rate_4xx": 0.0112,
        "error_rate_5xx": 0.0002,
        "edge_time_p95_ms": 455
      },
      "series": [
        {
          "time": "2026-11-01T18:00:00Z",
          "requests": 650,
          "visits": 222,
          "bytes": 14100222,
          "errors_4xx": 7,
          "errors_5xx": 0
        }
      ]
    },
    "breakdowns": {
      "country": [
        {
          "value": "BR",
          "label": null,
          "requests": 14210,
          "visits": 4902,
          "bytes": 318400221
        },
        {
          "value": "US",
          "label": null,
          "requests": 2105,
          "visits": 760,
          "bytes": 48112003
        },
        {
          "value": "PT",
          "label": null,
          "requests": 611,
          "visits": 204,
          "bytes": 13920110
        }
      ],
      "path": [
        {
          "value": "/",
          "label": null,
          "requests": 5210,
          "visits": 4100,
          "bytes": 90211003
        },
        {
          "value": "/pricing",
          "label": null,
          "requests": 1902,
          "visits": 1180,
          "bytes": 41230991
        }
      ],
      "referer": [
        {
          "value": "(none)",
          "label": null,
          "requests": 9120,
          "visits": 3300,
          "bytes": 201004112
        },
        {
          "value": "google.com",
          "label": null,
          "requests": 4410,
          "visits": 1890,
          "bytes": 98114003
        }
      ],
      "asn": [
        {
          "value": "28573",
          "label": "CLARO S.A.",
          "requests": 3300,
          "visits": 1100,
          "bytes": 70112008
        }
      ],
      "cache_status": [
        {
          "value": "hit",
          "label": null,
          "requests": 13011,
          "visits": 0,
          "bytes": 301100001
        },
        {
          "value": "dynamic",
          "label": null,
          "requests": 4100,
          "visits": 0,
          "bytes": 90113002
        }
      ]
    }
  }
}

Visão geral

Endpoints

Tráfego da aplicação

Filtros

Resposta

Observações

Respostas de erro

​Filtros

​Resposta

​Observações

​Respostas de erro

Filtros

Resposta

Observações

Respostas de erro