---
title: "Query analytics totals and breakdowns"
method: GET
path: "/websites/{websiteId}/analytics/query"
tags: ["Analytics"]
---

# Query analytics totals and breakdowns

`GET /websites/{websiteId}/analytics/query`

## Request

- Base URL: `https://api.cactal.ai/v1`
- URL: `https://api.cactal.ai/v1/websites/{websiteId}/analytics/query`
- Auth: HTTP bearer

Returns aggregate engagement totals — page views, distinct visitors, visits, bounces, and total time in seconds — for a date range, optionally broken down by one dimension. Use it to answer "how much traffic did the site get" and "what are the top pages/referrers/countries" style questions; use the timeseries endpoint when you need values over time instead. `startAt` and `endAt` are Unix epoch milliseconds; optional filter parameters (path, referrer, country, event, UTM fields, ...) narrow the data. Without `dimension` the response carries the totals alone. With `dimension` (e.g. `path` for top pages, `referrer` for top referrers, `country` for top countries) the response also carries `rows`: up to `limit` (default 25, max 1000) values of that dimension ranked by page views, each with its own engagement totals. Requires a plan that includes analytics (403 otherwise); all-zero totals until the website is published and has traffic.

## Path parameters

- `websiteId` string, required

## Query parameters

- `startAt` integer, required
- `endAt` integer, required
- `path` string
- `referrer` string
- `title` string
- `query` string
- `browser` string
- `os` string
- `device` string
- `country` string
- `region` string
- `city` string
- `language` string
- `hostname` string
- `tag` string
- `event` string
- `distinctId` string
- `utmSource` string
- `utmMedium` string
- `utmCampaign` string
- `utmContent` string
- `utmTerm` string
- `segment` string, uuid
- `cohort` string, uuid
- `dimension` 'path' | 'entry' | 'exit' | 'title' | 'query' | 'referrer' | 'channel' | 'domain' | 'country' | 'region' | 'city' | 'browser' | 'os' | 'device' | 'language' | 'screen' | 'event' | 'hostname' | 'tag' | 'distinctId': Break the range down by this dimension, e.g. `path` for top pages, `referrer` for top referrers, `country` for top countries. Omit for totals only.
- `limit` integer: Maximum number of dimension rows to return (default 25, max 1000). Only used when `dimension` is set.

## Response `200`

Engagement totals for the range, plus ranked `rows` when a `dimension` was requested.

- object
  - `pageviews` number, required: Total page views.
  - `visitors` number, required: Distinct visitors.
  - `visits` number, required: Visits (sessions).
  - `bounces` number, required: Single-page visits.
  - `totaltime` number, required: Total time spent in seconds, summed across visits.
  - `comparison` object: Totals for the comparison period, present when the provider computes one.
    - `pageviews` number, required: Total page views.
    - `visitors` number, required: Distinct visitors.
    - `visits` number, required: Visits (sessions).
    - `bounces` number, required: Single-page visits.
    - `totaltime` number, required: Total time spent in seconds, summed across visits.
  - `rows` object[]: Values of the requested `dimension` ranked by page views, each with its own engagement totals. Present only when `dimension` is set.
    - `name` string, required: Dimension value, e.g. the URL path, referrer domain, or country code.
    - `pageviews` number, required: Total page views.
    - `visitors` number, required: Distinct visitors.
    - `visits` number, required: Visits (sessions).
    - `bounces` number, required: Single-page visits.
    - `totaltime` number, required: Total time spent in seconds, summed across visits.

## Other responses

- `400`: Validation failed. The response `message` names the first invalid field.
- `401`: Missing, invalid, expired, or revoked API key.
- `403`: The authenticated principal lacks the required capability.
- `404`: The resource does not exist or is outside the principal’s access scope.
- `429`: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.

---

[API](https://skmtc.dev/cactal/apis/cactal-api.md) · [All operations](https://skmtc.dev/cactal/apis/cactal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cactal/apis/cactal-api/revisions/9cd0fb5eacdd?raw)