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

# Website Analytics

> Get analytics for a website hosted on Square Cloud. There is a rate limit of 10 uncached requests every 60 seconds.

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

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; a cache miss counts against a 10-requests-per-60-seconds-per-owner limit, so polling the same window repeatedly is cheap. 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 paid 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, as returned in the `providers` breakdown — e.g. `GOOGLE (15169)`, a bare ASN number, or `SQUARE-CLOUD-PLATFORM`.
</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 successful, `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={null}
  {
    "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": "AS15169 (GOOGLE)", "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.         |
| `UNABLE_TO_FETCH_ANALYTICS` | 500  | Failed to fetch analytics from the edge provider.               |