---
title: "Conversation analytics for an inbox"
method: GET
path: "/api/inboxes/{channelId}/analytics"
tags: ["Inboxes"]
---

# Conversation analytics for an inbox

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

## Request

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

Aggregated conversation metrics for one inbox over a date range.

Response times are **business-hours aware** — they use the company's
configured business hours and holidays, the same basis as in-app reports, so
figures reconcile. `responseCount` is the number of replies the averages were
computed from.

Averages and rates are `null` rather than `0` when the window contains
nothing to measure. Automated/junk threads are excluded unless
`includeJunk=true`.

`sentiment` carries a numeric average plus the `coverage` it was computed
from, and `enabled` reports whether scoring is currently switched on for the
inbox. Scores exist only for threads the pipeline actually scored, so a
coverage of 40% means the average describes 40% of the window's threads.
`topics` lists the categories applied to threads in the window with their
thread counts.

Qualitative tone summaries (prose descriptions of tone) are not part of this
endpoint yet and are absent from the response rather than returned as null.

## Path parameters

- `channelId` string, required

## Query parameters

- `dateFrom` string, date-time
- `dateTo` string, date-time
- `groupBy` 'assignee' | 'contactType'
- `includeJunk` boolean

## Response `200`

Aggregated metrics for the window.

- object
  - `data` InboxAnalytics: Averages and rates are null (not 0) when the window has nothing to measure.
    - `threadCount` integer
    - `contactCount` integer: Distinct counterparts across the matching threads.
    - `volume` object
      - `in` integer
      - `out` integer
      - `total` integer
    - `avgFirstResponseHrs` number, nullable
    - `avgResponseHrs` number, nullable
    - `responseCount` integer: Replies the averages were computed from.
    - `oneTouchPct` number, nullable: Percentage of threads resolved with a single outbound.
    - `oneTouchCount` integer
    - `reopenRatePct` number, nullable
    - `reopenedCount` integer
    - `noCustomerResponseCount` integer: Threads where we sent something and never got a reply.
    - `awaitingOurReplyCount` integer: Open threads where the counterpart spoke last.
    - `sentiment` InboxSentiment: AI sentiment for the window. Scores are produced on write by the enhancement pipeline, only for inboxes where it is switched on, so `coverage` is always reported next to the average — an average over a fraction of the threads must not be read as covering all of them.
      - `enabled` boolean: Whether sentiment scoring is currently on for this inbox (org AI assistant + org sentiment + the inbox's own feature flag). Reported at the inbox level only, not per group.
      - `avg` number, nullable: Mean score across scored threads. Null when none were scored.
      - `coverage` object
        - `scoredThreads` integer
        - `threadCount` integer
        - `pct` number, nullable
    - `window` object
      - `from` string, date-time, nullable
      - `to` string, date-time, nullable
    - `topics` InboxTopic[]
      - `topicId` string
      - `label` string, nullable
      - `emoji` string, nullable
      - `color` string, nullable
      - `threadCount` integer
    - `groupBy` 'assignee' | 'contactType', nullable
    - `groups` object[]: Present only when `groupBy` was supplied.
      - `key` string, nullable: Assignee user id or contact-type id. Null for unassigned.
      - `label` string, nullable
      - `threadCount` integer
      - `contactCount` integer: Distinct counterparts across the matching threads.
      - `volume` object
        - `in` integer
        - `out` integer
        - `total` integer
      - `avgFirstResponseHrs` number, nullable
      - `avgResponseHrs` number, nullable
      - `responseCount` integer: Replies the averages were computed from.
      - `oneTouchPct` number, nullable: Percentage of threads resolved with a single outbound.
      - `oneTouchCount` integer
      - `reopenRatePct` number, nullable
      - `reopenedCount` integer
      - `noCustomerResponseCount` integer: Threads where we sent something and never got a reply.
      - `awaitingOurReplyCount` integer: Open threads where the counterpart spoke last.
      - `sentiment` InboxSentiment: AI sentiment for the window. Scores are produced on write by the enhancement pipeline, only for inboxes where it is switched on, so `coverage` is always reported next to the average — an average over a fraction of the threads must not be read as covering all of them.
        - `enabled` boolean: Whether sentiment scoring is currently on for this inbox (org AI assistant + org sentiment + the inbox's own feature flag). Reported at the inbox level only, not per group.
        - `avg` number, nullable: Mean score across scored threads. Null when none were scored.
        - `coverage` object
          - `scoredThreads` integer
          - `threadCount` integer
          - `pct` number, nullable

## Other responses

- `400`: Invalid date range or `groupBy` value.
- `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)