# Inbox analytics

Measure DM volume, time to first response, busiest hours, message sources and the accounts that get the most conversations.

The inbox analytics endpoints turn the message stream behind your [inbox](https://pozy.ai/docs/inbox) into reporting: how many messages came in and went out, how fast your team or your automations answered, when people write, and which accounts carry the load.

Every endpoint needs `fromDate` and takes the same filters: `toDate`, `profileId`, `platform` and `accountId`. The date range is at most 365 days.

## Volume

`GET /v1/analytics/inbox/volume` returns a summary, a daily series and a per-platform split in one call, enough for a KPI strip and a chart.

```bash cURL
curl "https://api.pozy.ai/v1/analytics/inbox/volume?profileId=6650c1e2a3b4c5d6e7f80911&fromDate=2026-10-01&toDate=2026-10-29" \
  -H "Authorization: Bearer $POZY_API_KEY"
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/analytics/inbox/volume?profileId=6650c1e2a3b4c5d6e7f80911&fromDate=2026-10-01&toDate=2026-10-29", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.summary);
```
```python Python
import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/analytics/inbox/volume",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "6650c1e2a3b4c5d6e7f80911", "fromDate": "2026-10-01", "toDate": "2026-10-29"},
    timeout=30,
)
print(resp.json()["summary"])
```

```json
{
  "success": true,
  "from": "2026-10-01",
  "to": "2026-10-29",
  "summary": { "received": 1840, "sent": 1622, "read": 1490, "failed": 12, "uniqueConversations": 611 },
  "timeseries": [{ "date": "2026-10-01", "received": 58, "sent": 51, "read": 47, "failed": 0 }],
  "byPlatform": [{ "platform": "instagram", "received": 1210, "sent": 1100, "read": 1032, "failed": 3 }]
}
```

## Response time

`GET /v1/analytics/inbox/response-time` pairs every received message with the next message sent in the same conversation and reports the gap.

| Field | Meaning |
| --- | --- |
| `summary.sampleSize` | Conversations that received a message **and** got a reply in the window |
| `summary.medianSeconds`, `p90Seconds`, `p99Seconds` | Percentiles of time to first response |
| `summary.meanSeconds`, `fastestSeconds`, `slowestSeconds` | The rest of the distribution |
| `histogram[]` | Fixed buckets with `lowerSeconds`, `upperSeconds` and `count`, ready for a bar chart |

Unanswered conversations are not in `sampleSize`. To get a reply rate, divide `sampleSize` by `summary.uniqueConversations` from the volume endpoint, or compare it with `summary.received`. Report the median and p90 together: a few slow weekends hide behind a good average.

## Busiest hours

`GET /v1/analytics/inbox/heatmap` returns day-of-week by hour buckets with `received`, `sent` and `read` counts. Pass `action` (`message.received`, `message.sent`, `message.read` or `all`) to focus on one direction.

- `dow` runs from `1` (Monday) to `7` (Sunday). Note this differs from [best time to post](https://pozy.ai/docs/analytics/best-time), where `0` is Monday.
- Buckets are sparse: only cells with at least one message come back. Fill the rest with zeros to draw the full 7 by 24 grid.

Use it to staff the inbox, or to decide when a [workflow](https://pozy.ai/docs/automations/workflows) should answer instead of a person.

## Where messages come from

`GET /v1/analytics/inbox/source-breakdown` splits messages by what produced them: people, workflows, sequences, broadcasts, comment automations, the API, or the platform itself. Each source row has a per-platform sub-split. It tells you how much of the inbox your automations handle.

## Top accounts

`GET /v1/analytics/inbox/top-accounts` ranks accounts by message volume, with `received`, `sent`, `conversations`, `repliedCount` and `medianResponseSeconds` per account. `limit` goes up to 50. An account that has been disconnected stays in the list with a placeholder name, so totals still add up.

## Per conversation

- `GET /v1/analytics/inbox/conversations` lists conversations with per-row totals (`received`, `sent`, `read`, `failed`, `totalMessages`) and first and last message times. Sort with `sortBy` (`lastMessageAt`, `firstMessageAt`, `totalMessages`, `received`, `sent`, `read`, `failed`) and `order`, and page with `page` and `limit`.
- `GET /v1/analytics/inbox/conversations/{conversationId}` returns one conversation's summary, a daily series and its source mix.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/analytics/inbox/volume`](https://pozy.ai/docs/api/getInboxVolume) | Get inbox messaging volume |
| [`GET /v1/analytics/inbox/heatmap`](https://pozy.ai/docs/api/getInboxHeatmap) | Get day × hour heatmap |
| [`GET /v1/analytics/inbox/source-breakdown`](https://pozy.ai/docs/api/getInboxSourceBreakdown) | Get inbox source breakdown |
| [`GET /v1/analytics/inbox/response-time`](https://pozy.ai/docs/api/getInboxResponseTime) | Get inbox response-time stats |
| [`GET /v1/analytics/inbox/top-accounts`](https://pozy.ai/docs/api/getInboxTopAccounts) | Get top accounts by inbox volume |
| [`GET /v1/analytics/inbox/conversations`](https://pozy.ai/docs/api/listInboxConversationAnalytics) | List conversation analytics |
| [`GET /v1/analytics/inbox/conversations/{conversationId}`](https://pozy.ai/docs/api/getInboxConversationAnalytics) | Get conversation analytics |