> ## Documentation Index
> Fetch the complete documentation index at: https://developers.sapot.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Report Tools
> Reference for the reports:read MCP tools — KPI summaries, time series, live counts, and per-entity leaderboards over the v2 reporting API.
The report tools are read-only analytics over Sapot Chat's v2 reporting API. They cover a KPI summary for a window, a single metric bucketed over time, conversation counts by dimension, a per-entity leaderboard, and a real-time snapshot.
All five require the **`reports:read`** scope. A key without it gets an auth error naming the missing scope — that is the default-deny model, not a bug.
Time arguments (`since` / `until`) are **UNIX epoch SECONDS passed as strings** (e.g. `"1719792000"`), not ISO date strings. This is the single most common mistake with these tools.
## Scoping a report
`get_report_summary` and `get_report_timeseries` default to the whole account. To scope to one agent, inbox, label, or team, set `report_type` and pass the matching `entity_id`.
| `report_type` | `entity_id` |
| ------------------------------------ | ------------------------------------ |
| `account` (default) | not used |
| `agent` / `inbox` / `label` / `team` | **required** — the id of that entity |
`entity_id` is required whenever `report_type` is not `account`. Omitting it on a scoped report yields an error or an empty result.
## get\_report\_summary
KPI summary for a time window, plus the equivalent **prior window** for comparison.
**Arguments**
| Argument | Type | Required | Description |
| ------------- | ------- | ----------- | ------------------------------------------------------------- |
| `since` | string | yes | Window start — UNIX epoch **seconds** as a string. |
| `until` | string | yes | Window end — UNIX epoch **seconds** as a string. |
| `report_type` | string | no | `account` (default), or `agent` / `inbox` / `label` / `team`. |
| `entity_id` | integer | conditional | The entity id; required when `report_type` is not `account`. |
**Returns** an object with the current window's metrics and a `previous` object carrying the same keys for the prior window:
```json theme={null}
{
"conversations_count": 128,
"incoming_messages_count": 540,
"outgoing_messages_count": 612,
"avg_first_response_time": 340,
"avg_resolution_time": 5400,
"resolutions_count": 96,
"reply_time": 210,
"previous": { "conversations_count": 110, "...": "...same keys..." }
}
```
## get\_report\_timeseries
Time-bucketed values for a **single** metric.
**Arguments**
| Argument | Type | Required | Description |
| ------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `metric` | string | yes | e.g. `conversations_count`, `incoming_messages_count`, `avg_first_response_time`, `resolutions_count`, `reply_time`. |
| `since` | string | yes | Window start — UNIX epoch **seconds** as a string. |
| `until` | string | yes | Window end — UNIX epoch **seconds** as a string. |
| `group_by` | string | no | Bucket size: `day` (default), `week`, or `month`. |
| `report_type` | string | no | `account` (default), or `agent` / `inbox` / `label` / `team`. |
| `entity_id` | integer | conditional | Required when `report_type` is not `account`. |
**Returns** a list of `{ value, timestamp }` buckets:
```json theme={null}
[
{ "value": 18, "timestamp": 1719792000 },
{ "value": 22, "timestamp": 1719878400 }
]
```
## get\_conversation\_counts
Conversation-count metrics grouped by a dimension. Takes no time window.
**Arguments**
| Argument | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------------------- |
| `report_type` | string | yes | One of `account`, `agent`, `inbox`, `label`, `team`. |
**Returns** the conversation-count metrics for that grouping.
## get\_entity\_summary
A per-entity **leaderboard** — one aggregated row per agent, team, inbox, label, or channel over a window.
**Arguments**
| Argument | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------------------- |
| `entity` | string | yes | One of `agent`, `team`, `inbox`, `label`, `channel`. |
| `since` | string | yes | Window start — UNIX epoch **seconds** as a string. |
| `until` | string | yes | Window end — UNIX epoch **seconds** as a string. |
**Returns** a list of rows, one per entity, each with its aggregated metrics.
`entity="channel"` is capped to a **6-month** range by the API — keep `since`/`until` within six months when summarising by channel.
## get\_live\_reports
A **real-time snapshot** of current conversation counts. No time window.
**Arguments**
| Argument | Type | Required | Description |
| --------- | ------- | -------- | --------------------------------------- |
| `team_id` | integer | no | Restrict the snapshot to a single team. |
**Returns**
```json theme={null}
{ "open": 42, "unattended": 7, "unassigned": 12, "pending": 3 }
```
## Recipe — weekly readout
Turn your date range into UNIX epoch **seconds** (strings) — e.g. last Monday 00:00 → this Monday 00:00.
`get_report_summary(since, until)` returns this week plus `previous` for a week-over-week read.
`get_entity_summary(entity="agent", since, until)` for per-agent rows.
`get_live_reports()` for the current open / unattended / unassigned / pending counts.
## Errors you may see
* **`missing the required scope: reports:read`** — the key wasn't granted reporting access. Add the scope in the dashboard, or leave it off on purpose. See the Authentication & Scopes reference at /ai-agents/authentication.
* **`Agent action quota exceeded for the current billing period`** (`429`) — the account's plan MCP-action allowance is used up for the period. It resets at the next billing renewal; upgrading raises the cap.
Every successful report call is a metered action against your plan. When you need only totals for a filter (not analytics), a single `count_conversations` call is cheaper than a full report — see the conversation tools reference.