# Analytics API

> Overview metrics, time series, breakdowns by dimension, revenue attribution and CSV export, with every dimension and metric listed.

Section: CLI, MCP and API  
Canonical page: https://statsy.co/docs/developers/api-analytics  
Last updated: 2026-09-15

These four endpoints answer most questions. They all share the range, `tz`, `filters` and `segment` parameters described in the [REST API overview](https://statsy.co/docs/developers/api).

## Overview

`GET /sites/:site/overview` returns the headline metrics for a range. With `compare=prev` each metric also carries the previous period’s value and the percentage change.

```bash
curl -H "Authorization: Bearer sta_your_token" \
  "https://statsy.co/api/v1/sites/ws_yoursitekey/overview?from=30d&compare=prev"
```

The metric keys are `visitors`, `pageviews`, `sessions`, `bounce_rate`, `avg_duration_s`, `conversions`, `conversion_rate`, `revenue`, `revenue_per_visitor` and `customers`. Each is an object of `value`, `prev` and `delta_pct`.

## Time series

`GET /sites/:site/timeseries` returns one metric bucketed over time, with empty buckets filled in.

| Parameter | Values | Default |
| --- | --- | --- |
| `metric` | `visitors`, `pageviews`, `sessions`, `conversions`, `revenue`, `customers` | `visitors` |
| `granularity` | `hour`, `day`, `week`, `month` | `day`, or `hour` for the `now` preset |
| `compare` | `prev` | — |

The response carries `series` as `{t, value}` pairs, `prev_series` when comparing, and `requested_granularity` in case an hourly request had to be coarsened to days for a long range.

## Breakdown

`GET /sites/:site/breakdown` returns the top values of one dimension, each with visitors, pageviews, conversions, revenue and customers.

```bash
curl -H "Authorization: Bearer sta_your_token" \
  "https://statsy.co/api/v1/sites/ws_yoursitekey/breakdown?dimension=channel&metric=revenue&limit=20&from=90d"
```

`dimension` defaults to `path` and accepts `path`, `referrer_host`, `channel`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `country`, `region`, `city`, `device`, `browser`, `os`, `lang`, `screen`, `goal`, `ai_source`, `post`, `entry_path`, `exit_path` and `keyword`.

`metric` chooses the sort order and must be `visitors`, `pageviews`, `conversions` or `revenue`. `limit` defaults to 50 and tops out at 500; page with `cursor`. Region rows also carry `country`, and city rows carry both.

## Attribution

`GET /sites/:site/attribution` credits real payments to the channels that brought the buyer. `model` is `last`, `first`, `linear`, `time_decay` or `position`, defaulting to `last`. `lookback` is the number of days of touches considered before each payment, from 1 to 365, defaulting to 90.

Rows carry visitors, customers, conversions, revenue, refunds, net and ARPU. See [Revenue attribution](https://statsy.co/docs/revenue) for what the models mean.

## CSV export

`GET /sites/:site/export` streams a full breakdown as CSV rather than JSON. Pass `dimension`, `metric` and `format=csv`. It returns up to 50,000 rows, and a workspace may run two exports at once before getting `429 export_busy`.

```bash
curl -H "Authorization: Bearer sta_your_token" \
  "https://statsy.co/api/v1/sites/ws_yoursitekey/export?dimension=path&from=90d" -o pages.csv
```

## Bots, notes and segments

`GET /sites/:site/bots` reports crawler traffic by `family`, `name` or `path`, separately from human visitors. `/sites/:site/notes` creates, lists, updates and deletes chart annotations, and `/sites/:site/segments` does the same for saved filter sets you can then pass as `segment`.

Previous: [REST API overview](https://statsy.co/docs/developers/api)  
Next: [Realtime API](https://statsy.co/docs/developers/api-realtime)