---
title: "Volume health for an inbox against its own baseline"
method: GET
path: "/api/inboxes/{channelId}/health"
tags: ["Inboxes"]
---

# Volume health for an inbox against its own baseline

`GET /api/inboxes/{channelId}/health`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/inboxes/{channelId}/health`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/inboxes/:channelId/health/get.ts> (a function with typed inputs; its response is checked against the schema)

Compares the requested window's message volume against this inbox's own
recent norm and scores the deviation, for health/risk surfaces.

The baseline is a trailing average of the `baselinePeriods` windows of the
same length immediately before `dateFrom` (default 3). No seasonal
adjustment is applied. `dateFrom` and `dateTo` are both required; the window
plus its baseline must stay within a 400-day scan, so long ranges need a
lower `baselinePeriods`.

`severityScore` (0–100) tracks the size of a **decline** — growth scores 0
with label `none`. Bands: `critical` 75+, `high` 50–74, `moderate` 25–49,
`low` 1–24.

`trend` compares the two halves of the requested window, which is what
separates "down and still falling" from "down but recovering".

**Insufficient history is reported explicitly.** With no baseline volume,
`volumeVsBaselinePct` and `severityScore` are `null` and `severityLabel` is
`insufficient_history` — a silent `-100%` would be indistinguishable from a
real collapse and would drive alerts the data can't justify.

## Path parameters

- `channelId` string, required

## Query parameters

- `dateFrom` string, date-time, required
- `dateTo` string, date-time, required
- `baselinePeriods` integer
- `includeJunk` boolean

## Response `200`

Volume health for the window.

- object
  - `data` InboxHealth
    - `window` object
      - `from` string, date-time
      - `to` string, date-time
    - `baseline` object
      - `from` string, date-time
      - `to` string, date-time
      - `periods` integer
      - `avgVolume` number, nullable: Mean volume per period across the baseline span.
      - `sufficient` boolean: False when the baseline span carried no volume. Everything derived from the baseline is null in that case.
    - `volume` integer: Messages in the requested window.
    - `volumeVsBaselinePct` number, nullable: Percentage change against the baseline average. Negative is a decline. Null when `baseline.sufficient` is false.
    - `trend` 'falling' | 'rising' | 'flat' | 'unknown': Second half of the window vs. the first. `unknown` when the window is too short to split.
    - `severityScore` integer, nullable: 0–100, tracking decline magnitude. 0 for flat or growing volume.
    - `severityLabel` 'critical' | 'high' | 'moderate' | 'low' | 'none' | 'insufficient_history'
    - `tags` string[]: Human-readable flags, e.g. `Usage down`, `No activity`, `Still falling`.

## Other responses

- `400`: Missing window, invalid `baselinePeriods`, or a window plus baseline exceeding the 400-day scan limit.
- `401`: Invalid or missing credential.
- `403`: The authenticated user cannot reach this inbox.
- `404`: Inbox not found in your company.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)