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

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