---
title: "Get an analytics time series"
method: GET
path: "/websites/{websiteId}/analytics/timeseries"
tags: ["Analytics"]
---

# Get an analytics time series

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

## Request

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

Returns one traffic time series bucketed by `unit` (`year`, `month`, `day`, `hour`, or `minute`). `series` selects which: `pageviews` returns parallel `pageviews` and `sessions` arrays with one point per time bucket (and accepts `compare` — `prev` or `yoy` — to request comparison data for the previous period or year), while `events` returns tracked custom-event counts as one `events` point per event name per time bucket. Only the requested series' fields are present in the response. `startAt` and `endAt` are Unix epoch milliseconds; `timezone` is an IANA name (e.g. `America/New_York`) that controls bucket boundaries; optional filter parameters narrow the data. The series is capped to the most recent `maxPoints` time buckets (default 30, max 500); a `truncated` field reports when the cap was applied. Requires a plan that includes analytics (403 otherwise); empty 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
- `unit` 'year' | 'month' | 'day' | 'hour' | 'minute', required
- `timezone` string
- `maxPoints` integer
- `series` 'pageviews' | 'events', required: Which time series to return: `pageviews` for page views and sessions per bucket, `events` for tracked custom-event counts per event name per bucket.
- `compare` 'prev' | 'yoy': Request comparison data alongside the primary series: `prev` for the previous period, `yoy` for the same range one year earlier. Only valid when `series` is `pageviews`.

## Response `200`

The requested time series: `pageviews` and `sessions` per bucket, or `events` per event name per bucket.

- object
  - `pageviews` object[]: Page views per time bucket. Present only when `series` is `pageviews`.
    - `x` string, required: Start of the time bucket.
    - `y` number, required: Count in the bucket.
  - `sessions` object[]: Distinct sessions per time bucket. Present only when `series` is `pageviews`.
    - `x` string, required: Start of the time bucket.
    - `y` number, required: Count in the bucket.
  - `events` object[]: One point per event name per time bucket. Present only when `series` is `events`.
    - `x` string, required: Event name.
    - `t` string, required: Start of the time bucket.
    - `y` number, required: Number of events in the bucket.
  - `truncated` object: Present only when the series exceeded `maxPoints` and was capped to the most recent time buckets.
    - `shown` integer, required: Time buckets returned.
    - `total` integer, required: Time buckets the range produced.
    - `hint` string, required: How to retrieve the rest.

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