> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Obter analytics de tráfego do site

> Obtenha analytics de tráfego na borda dos domínios de uma aplicação com GET /v2/apps/{app_id}/network/analytics: requisições, banda, visitantes e detalhes.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `apps:read`.

A Análise agrega o tráfego de borda do Cloudflare para o domínio `squareweb.app` padrão da aplicação e qualquer domínio personalizado associado: contagem de requisições, banda, contagem de visitantes e detalhamentos por país, dispositivo, sistema operacional, navegador, protocolo, método, caminho, referer e rede do cliente. Use-a para montar dashboards de tráfego ou identificar padrões incomuns sem precisar puxar logs brutos de requisições.

Os resultados ficam em cache em blocos de 5 minutos, então fazer polling repetido da mesma janela é barato. O cache miss compartilha um limite único de 20 requisições por 60 segundos por proprietário da aplicação, entre os endpoints de análise, erros, logs e performance. Respostas em cache não contam. Em períodos de alta demanda em toda a plataforma, o endpoint pode retornar os dados em cache mais recentes da janela solicitada. A janela máxima de retenção é de 7 dias, e o início efetivo é limitado à data de criação da aplicação. Diferente de [Logs de rede](/pt-br/api-reference/endpoint/apps/network/logs) e [Performance de rede](/pt-br/api-reference/endpoint/apps/network/performance), este endpoint está disponível em todos os planos, não apenas Pro e Enterprise.

Para tráfego focado em erros em vez de tráfego geral, veja [Erros de rede](/pt-br/api-reference/endpoint/apps/network/errors). Para limpar as respostas em cache na borda após um deploy, veja [Limpar cache](/pt-br/api-reference/endpoint/apps/network/purge_cache).

## Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL da sua aplicação no dashboard.
</ParamField>

<ParamField query="start" type="string" placeholder="Timestamp ISO 8601" required>
  Timestamp inicial em formato ISO 8601 para a janela de análise. A janela máxima de retenção é de 7 dias; o início é limitado à data de criação da aplicação.
</ParamField>

<ParamField query="end" type="string" placeholder="Timestamp ISO 8601" required>
  Timestamp final em formato ISO 8601. Deve ser posterior ao `start`.
</ParamField>

### Filtros de detalhamento

Filtros opcionais que restringem **todos** os detalhamentos ao tráfego correspondente. Reutilize o valor `type` exato retornado pelo detalhamento correspondente em uma resposta anterior. Os filtros combinam entre si (E lógico).

<ParamField query="country" type="string" placeholder="BR">
  Um único país do cliente (código de 2 caracteres), conforme retornado no detalhamento `countries`.
</ParamField>

<ParamField query="ip" type="string" placeholder="203.0.113.45">
  Um único IP do cliente (correspondência exata IPv4/IPv6), conforme retornado no detalhamento `ips`.
</ParamField>

<ParamField query="path" type="string" placeholder="/api">
  Caminhos de requisição que começam com este prefixo (ex.: `/api` cobre `/api/*`). Máx. 256 caracteres.
</ParamField>

<ParamField query="status" type="string" placeholder="404">
  Um único código de status de resposta da edge (3 dígitos), conforme retornado no detalhamento `status_codes`.
</ParamField>

<ParamField query="os" type="string" placeholder="Windows">
  Um único sistema operacional do cliente, conforme retornado no detalhamento `os`.
</ParamField>

<ParamField query="browser" type="string" placeholder="Chrome">
  Um único navegador do cliente, conforme retornado no detalhamento `browsers`.
</ParamField>

<ParamField query="protocol" type="string" placeholder="HTTP/2">
  Um único protocolo HTTP, conforme retornado no detalhamento `protocols`.
</ParamField>

<ParamField query="referer" type="string" placeholder="google.com">
  Um único host de referência, conforme retornado no detalhamento `referers` (`Direct` = sem referer).
</ParamField>

<ParamField query="provider" type="string" placeholder="GOOGLE (15169)">
  Uma única rede do cliente, com o valor exato de `type` que o detalhamento `providers` retorna, por exemplo `GOOGLE (15169)`. Um número de ASN puro ou `SQUARE-CLOUD-PLATFORM` também funcionam. Qualquer outro valor responde `INVALID_FILTER`.
</ParamField>

<ParamField query="content_type" type="string" placeholder="json">
  Um único tipo de conteúdo da resposta, conforme retornado no detalhamento `content_types` (`Unknown` = não classificado).
</ParamField>

<ParamField query="bot" type="string" placeholder="Search Engine Crawler">
  Uma única categoria de bot verificado, conforme retornada no detalhamento `bots` (`Unverified` = tráfego regular, não-bot).
</ParamField>

## Resposta

<Info>
  Esta rota pode retornar uma resposta em formato compactado, otimizando a transmissão de dados.
</Info>

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

<ResponseField name="response" type="object">
  Cada detalhamento é um array de buckets. `type` identifica a dimensão, `visits` é o número de visitantes únicos, `requests` é a contagem de requisições, `bytes` é o total de bytes servidos na resposta, e `date` é o início da janela de 15 minutos. Os detalhamentos `ips`, `status_codes`, `bots` e `content_types` são totais da janela (top-N sobre toda a janela) e **não** possuem o campo `date`. Retorna um objeto vazio (`{}`) quando a janela solicitada começa antes da data de criação da aplicação.
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
    "status": "success",
    "response": {
      "visits": [
        { "visits": 1024, "requests": 1247, "bytes": 8421000, "date": "2026-05-21T10:00:00Z" }
      ],
      "countries": [
        { "type": "BR", "visits": 612, "requests": 743, "bytes": 5012000, "date": "2026-05-21T10:00:00Z" }
      ],
      "devices": [
        { "type": "desktop", "visits": 820, "requests": 998, "bytes": 6700000, "date": "2026-05-21T10:00:00Z" }
      ],
      "os": [
        { "type": "Windows", "visits": 540, "requests": 651, "bytes": 4400000, "date": "2026-05-21T10:00:00Z" }
      ],
      "browsers": [
        { "type": "Chrome", "visits": 720, "requests": 870, "bytes": 5800000, "date": "2026-05-21T10:00:00Z" }
      ],
      "protocols": [
        { "type": "HTTP/2", "visits": 900, "requests": 1100, "bytes": 7400000, "date": "2026-05-21T10:00:00Z" }
      ],
      "methods": [
        { "type": "GET", "visits": 850, "requests": 1020, "bytes": 6900000, "date": "2026-05-21T10:00:00Z" }
      ],
      "paths": [
        { "type": "/", "visits": 410, "requests": 498, "bytes": 3320000, "date": "2026-05-21T10:00:00Z" }
      ],
      "referers": [
        { "type": "Direct", "visits": 380, "requests": 462, "bytes": 3100000, "date": "2026-05-21T10:00:00Z" }
      ],
      "providers": [
        { "type": "GOOGLE (15169)", "visits": 210, "requests": 254, "bytes": 1700000, "date": "2026-05-21T10:00:00Z" }
      ],
      "ips": [
        { "type": "203.0.113.45", "visits": 40, "requests": 3120, "bytes": 2100000 }
      ],
      "status_codes": [
        { "type": "200", "visits": 950, "requests": 1180, "bytes": 8100000 }
      ],
      "bots": [
        { "type": "Search Engine Crawler", "visits": 0, "requests": 84, "bytes": 410000 }
      ],
      "content_types": [
        { "type": "json", "visits": 310, "requests": 720, "bytes": 4200000 }
      ]
    }
  }
  ```
</ResponseExample>

## Erros comuns

| Código | HTTP | Significado |
| - | - | - |
| `INVALID_TIME_RANGE` | 400 | `start`/`end` estão ausentes, malformados ou invertem o intervalo de tempo. |
| `INVALID_FILTER` | 400 | Um filtro de detalhamento não corresponde ao formato esperado. |
| `RATE_LIMITED` | 429 | O limite compartilhado de cache misses foi atingido. Aguarde e tente novamente. |
| `UNABLE_TO_FETCH_ANALYTICS` | 500 | Falha ao obter os dados de análise do provedor de edge. |
| `ANALYTICS_BUSY` | 503 | As análises de borda estão temporariamente ocupadas. Tente novamente em um minuto. |

## Relacionados

* CLI: [`squarecloud app network analytics`](/pt-br/cli-reference/edge-analytics#squarecloud-app-network-analytics)
* SDKs: [`api.apps.network.analytics()`](/pt-br/sdks/js/network) (JavaScript), [`client.apps.network.analytics()`](/pt-br/sdks/py/network) (Python), [`c.Apps.Network.Analytics()`](/pt-br/sdks/go/network) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.