---
title: "Time-bucketed metric series."
method: GET
path: "/stats/timeseries"
tags: ["Stats API"]
---

# Time-bucketed metric series.

`GET /stats/timeseries`

## Request

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

Returns one row per bucket (day/hour/month) over the period. `interval=hour` requires period=day; `interval=month` requires period >= 6mo, month, or custom.

## 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
- `interval` 'hour' | 'day' | 'month': `hour` requires period=day; `month` requires period of 6mo+, month, or custom.

## Response `200`

Successful timeseries.

- StatsTimeseriesResponse
  - `success` true, required
  - `data` object, required
    - `results` object[], required
      - `date` string, required: Bucket label: YYYY-MM-DD (day), YYYY-MM (month), or YYYY-MM-DDTHH:00 (hour).
    - `meta` object, required
      - `period` union
        - 'day' | '7d' | '30d' | 'month' | '6mo' | '12mo'
        - string: Custom range: `custom:YYYY-MM-DD,YYYY-MM-DD`. Max 366 days.
      - `interval` 'hour' | 'day' | 'month': `hour` requires period=day; `month` requires period of 6mo+, month, or custom.
      - `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
      - `note` string: With filters or interval=hour: how page views are counted. Buckets before page view tracking started for the site have pageviews null.
  - `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)