> ## 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.

# Get website traffic analytics

> Get edge traffic analytics for an application's domains with GET /v2/apps/{app_id}/network/analytics: requests, bandwidth, visitors and breakdowns.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes).

Analytics aggregates Cloudflare edge traffic for the application's default `squareweb.app` domain and any attached custom domain: request counts, bandwidth, visitor counts, and breakdowns by country, device, OS, browser, protocol, method, path, referer, and client network. Use it to build traffic dashboards or spot unusual patterns without pulling raw request logs.

Results are cached in 5-minute buckets, so polling the same window repeatedly is cheap. Cache misses share one limit of 20 requests per 60 seconds per application owner, across the analytics, errors, logs and performance endpoints. Cached responses do not count. During platform-wide busy periods the endpoint may return the most recent cached data for the requested window instead. The maximum lookback is 7 days, and the effective start is clamped to the application's creation date. Unlike [Network Logs](/en/api-reference/endpoint/apps/network/logs) and [Network Performance](/en/api-reference/endpoint/apps/network/performance), this endpoint is available on every plan, not just Pro and Enterprise.

For error-focused traffic instead of overall traffic, see [Network Errors](/en/api-reference/endpoint/apps/network/errors). To purge cached edge responses after a deploy, see [Purge Cache](/en/api-reference/endpoint/apps/network/purge_cache).

## Parameters

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  The ID of the application. You can find this in the URL of your application's dashboard.
</ParamField>

<ParamField query="start" type="string" placeholder="ISO 8601 timestamp" required>
  ISO 8601 start timestamp for the analysis window. The maximum retention window is 7 days; the start is clamped to the application's creation date.
</ParamField>

<ParamField query="end" type="string" placeholder="ISO 8601 timestamp" required>
  ISO 8601 end timestamp. Must be after `start`.
</ParamField>

### Drill-down filters

Optional filters that narrow **every** breakdown to the matching traffic. Feed back the exact `type` value returned by the corresponding breakdown in a previous response. Filters combine (AND).

<ParamField query="country" type="string" placeholder="BR">
  A single client country (2-character code), as returned in the `countries` breakdown.
</ParamField>

<ParamField query="ip" type="string" placeholder="203.0.113.45">
  A single client IP (exact IPv4/IPv6 match), as returned in the `ips` breakdown.
</ParamField>

<ParamField query="path" type="string" placeholder="/api">
  Request paths starting with this prefix (e.g. `/api` covers `/api/*`). Max 256 chars.
</ParamField>

<ParamField query="status" type="string" placeholder="404">
  A single edge response status code (3 digits), as returned in the `status_codes` breakdown.
</ParamField>

<ParamField query="os" type="string" placeholder="Windows">
  A single client OS, as returned in the `os` breakdown.
</ParamField>

<ParamField query="browser" type="string" placeholder="Chrome">
  A single client browser, as returned in the `browsers` breakdown.
</ParamField>

<ParamField query="protocol" type="string" placeholder="HTTP/2">
  A single HTTP protocol, as returned in the `protocols` breakdown.
</ParamField>

<ParamField query="referer" type="string" placeholder="google.com">
  A single referer host, as returned in the `referers` breakdown (`Direct` = no referer).
</ParamField>

<ParamField query="provider" type="string" placeholder="GOOGLE (15169)">
  A single client network, with the exact `type` value the `providers` breakdown returns, for example `GOOGLE (15169)`. A bare ASN number or `SQUARE-CLOUD-PLATFORM` also work. Any other value answers `INVALID_FILTER`.
</ParamField>

<ParamField query="content_type" type="string" placeholder="json">
  A single response content type, as returned in the `content_types` breakdown (`Unknown` = unclassified).
</ParamField>

<ParamField query="bot" type="string" placeholder="Search Engine Crawler">
  A single verified-bot category, as returned in the `bots` breakdown (`Unverified` = regular non-bot traffic).
</ParamField>

## Response

<Info>
  This route can send a response in a compressed format, optimizing data transmission.
</Info>

<ResponseField name="status" type="string">
  Indicates whether the call was successful: `success` if it was, `error` if not.
</ResponseField>

<ResponseField name="response" type="object">
  Each breakdown is an array of buckets. `type` identifies the dimension, `visits` is unique visitors, `requests` is the request count, `bytes` is the response bytes served, and `date` is the 15-minute window start. The `ips`, `status_codes`, `bots`, and `content_types` breakdowns are window totals (top-N over the whole window) and carry **no** `date` field. Returns an empty object (`{}`) when the requested window starts before the application's creation date.
</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>

## Common errors

| Code | HTTP | Meaning |
| - | - | - |
| `INVALID_TIME_RANGE` | 400 | `start`/`end` are missing, malformed, or invert the time range. |
| `INVALID_FILTER` | 400 | A drill-down filter does not match its expected format. |
| `RATE_LIMITED` | 429 | The shared limit of cache misses was reached. Wait and retry. |
| `UNABLE_TO_FETCH_ANALYTICS` | 500 | Failed to fetch analytics from the edge provider. |
| `ANALYTICS_BUSY` | 503 | Edge analytics are temporarily busy. Try again in a minute. |

## Related

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


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