---
title: "Project engagement rollup"
method: GET
path: "/v1/stats"
tags: ["Stats"]
---

# Project engagement rollup

`GET /v1/stats`

## Request

- Base URL: `https://api.volanea.com`
- URL: `https://api.volanea.com/v1/stats`
- Auth: HTTP bearer

Sends, delivery, opens, clicks, bounces and unsubscribes for the whole project over a window, with the previous window alongside for comparison and a gap-free daily series for charting.

**Test and live are separate populations**, and which one you get is decided by the key you authenticate with rather than by a parameter — a `sk_test_…` key can never report production figures. This matters more than it sounds: in a project that has been integrated against, more than half the rows in the send log can be test sends, and totalling `GET /v1/emails` without filtering them produces a delivery rate that is wrong by tens of points.

**Rates compare in points, sends compare in percent.** An open rate moving 35% → 38% is reported as `openPoints: 3`, because "open rate up 8%" is ambiguous and "up 3 points" is not. `sentPercent` is a true percentage change, and is `null` rather than 0 when the previous window had no sends at all — those are different facts.

`delivered` counts every message that reached the mailbox, so it includes the ones that went on to be opened and clicked. Statuses only move forward, so each stage necessarily contains the ones past it.

## Query parameters

- `days` integer

## Response `200`

The rollup.

- object
  - `window` object
    - `days` integer
    - `from` string, date-time
    - `to` string, date-time
  - `testMode` boolean: Which population these numbers describe, derived from the key.
  - `totals` object
    - `sent` integer
    - `delivered` integer
    - `opened` integer
    - `clicked` integer
    - `bounced` integer
    - `complained` integer
    - `failed` integer
    - `unsubscribed` integer
  - `rates` object: Percentages. `delivery` and `bounce` are of `sent`; `open`, `click` and `unsubscribe` are of `delivered`.
    - `delivery` number
    - `open` number
    - `click` number
    - `bounce` number
    - `unsubscribe` number
  - `previous` object: The same measures for the preceding window of equal length.
  - `change` object
    - `sentPercent` number, nullable: Percentage change in volume; null when the previous window had no sends.
    - `deliveryPoints` number
    - `openPoints` number
    - `clickPoints` number
  - `daily` object[]: One entry per day, oldest first, split by source. Days with no sends are present with zeros so a chart has no holes.
    - `day` string: YYYY-MM-DD.
    - `transactional` integer
    - `campaign` integer
    - `workflow` integer
    - `inbound` integer
    - `total` integer

## Other responses

- `401`: Missing or invalid API key.
- `422`: Request validation failed (code `validation_error`, 422).

---

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