---
title: "Group metrics by a dimension (page, country, browser, …)."
method: GET
path: "/stats/breakdown"
tags: ["Stats API"]
---

# Group metrics by a dimension (page, country, browser, …).

`GET /stats/breakdown`

## Request

- Base URL: `https://api.zenovay.com/api/external/v1`
- URL: `https://api.zenovay.com/api/external/v1/stats/breakdown`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Returns metrics grouped by the specified `property`, sorted by visitors descending, with pagination.

**event:page:** pages by real page views. `page` is the path (`/pricing`) for pages on the site's own domain and host + path (`blog.example.com/`) for other hosts; query strings and trailing slashes are dropped. `visitors` = visits that viewed the page. At most the top 500 pages. Page views are counted from the start of page view tracking for the site (`meta.note` says so when the period starts earlier). When no page view data is available, landing pages are listed (same labels), with page views approximated by landing visits.

**Other properties:** `visitors` = visits of the group. `pageviews`, `events` and `bounce_rate` are real page views of the group's visits (up to 5,000 visits in the period); beyond that, for `visit:device` and `visit:browser` they come from the Analytics KPI per group shown; otherwise `pageviews`/`events` are approximated by the visit count and `meta.note` says so. With filters they are `null` when they cannot be counted.

## Query parameters

- `site_id` string, uuid, required
- `period` union, required
  - 'day' | '7d' | '30d' | 'month' | '6mo' | '12mo'
  - string: Custom range: `custom:YYYY-MM-DD,YYYY-MM-DD`. Max 366 days.
- `date` string, date
- `metrics` string, required
- `filters` string
- `property` 'event:page' | 'visit:country' | 'visit:browser' | 'visit:device' | 'visit:os' | 'visit:source', required
- `limit` integer
- `page` integer

## Response `200`

Successful breakdown.

- StatsBreakdownResponse
  - `success` true, required
  - `data` object, required
    - `results` object[], required
    - `meta` object, required
      - `period` union
        - 'day' | '7d' | '30d' | 'month' | '6mo' | '12mo'
        - string: Custom range: `custom:YYYY-MM-DD,YYYY-MM-DD`. Max 366 days.
      - `period_start` string, date-time
      - `period_end` string, date-time
      - `property` 'event:page' | 'visit:country' | 'visit:browser' | 'visit:device' | 'visit:os' | 'visit:source'
      - `filters_applied` FilterApplied[]
        - `key` 'country' | 'browser' | 'device' | 'os' | 'source' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'page', required
        - `operator` '==' | '!=', required
        - `values` string[], required
      - `pagination` object
        - `page` integer
        - `limit` integer
        - `total` integer
        - `has_more` boolean
      - `note` string: How page views were counted for this response (e.g. approximated by visits), and from which date page views are counted when the period starts earlier.
  - `timestamp` string, date-time, required

## Other responses

- `400`: Malformed request — missing required parameter or invalid value.
- `401`: Missing or invalid API key.
- `403`: Plan-gate: insufficient plan tier, or API key out of scope for the requested site.
- `404`: Site not found or not accessible from this key.
- `429`: Per-tier rate limit exceeded. Retry-After header indicates wait time in seconds.

---

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