---
title: "Aggregate metrics over a period."
method: GET
path: "/stats/aggregate"
tags: ["Stats API"]
---

# Aggregate metrics over a period.

`GET /stats/aggregate`

## Request

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

Returns single-number values for each requested metric over the specified period.

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

## Response `200`

Successful aggregate.

- StatsAggregateResponse
  - `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
      - `filters_applied` FilterApplied[]
        - `key` 'country' | 'browser' | 'device' | 'os' | 'source' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'page', required
        - `operator` '==' | '!=', required
        - `values` string[], required
      - `blended_today` boolean: Today was added live (stored days end yesterday). False when the period excludes today, a stored row for today exists, or the live figures were unavailable.
      - `note` string
  - `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)