---
title: "Volume and response-time trends for an inbox"
method: GET
path: "/api/inboxes/{channelId}/trends"
tags: ["Inboxes"]
---

# Volume and response-time trends for an inbox

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

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/inboxes/{channelId}/trends`
- 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/trends/get.ts> (a function with typed inputs; its response is checked against the schema)

A gap-free time series for one inbox, rolled up server-side by day, week,
month or quarter. Both `dateFrom` and `dateTo` are required (max 400 days);
`dateTo` is exclusive. Periods with no activity are returned with zero volume
rather than omitted, so the series can be charted directly.

All bucketing is UTC. Weeks start Monday (ISO) and are keyed by that Monday's
date, so week keys sort alongside day keys.

**Two bucketing bases, deliberately:** `volume` counts messages sent or
received *during* the period, while `threadCount` and the response/rate
figures describe threads whose *last activity* fell in the period. Response
times carry no per-message timestamps, so they can't be attributed to a
single day of a long-running thread. Do not divide `volume` by `threadCount`.

Averages are combined from underlying sums and counts, so a quiet day never
carries the same weight as a busy one. `responseCount` is the number of
replies behind `avgResponseHrs`.

## Path parameters

- `channelId` string, required

## Query parameters

- `dateFrom` string, date-time, required
- `dateTo` string, date-time, required
- `granularity` 'day' | 'week' | 'month' | 'quarter'
- `includeJunk` boolean

## Response `200`

Gap-free trend series, oldest period first.

- object
  - `data` object
    - `granularity` 'day' | 'week' | 'month' | 'quarter'
    - `window` object
      - `from` string, date-time
      - `to` string, date-time
    - `data` InboxTrendPeriod[]
      - `period` string: Period key. `YYYY-MM-DD` for day and week (week = the Monday it starts), `YYYY-MM` for month, `YYYY-Qn` for quarter.
      - `volume` object: Messages sent or received during this period.
        - `in` integer
        - `out` integer
        - `total` integer
      - `threadCount` integer: Threads whose last activity fell in this period.
      - `avgResponseHrs` number, nullable: Business hours. Null when the period had no replies.
      - `responseCount` integer: Replies behind avgResponseHrs.
      - `avgFirstResponseHrs` number, nullable
      - `oneTouchPct` number, nullable
      - `reopenRatePct` number, nullable

## Other responses

- `400`: Missing/invalid window, or invalid granularity.
- `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)