Skip to main content
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.
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 Returns an object with the current window’s metrics and a previous object carrying the same keys for the prior window:

​
get_report_timeseries

Time-bucketed values for a single metric. Arguments Returns a list of { value, timestamp } buckets:

​
get_conversation_counts

Conversation-count metrics grouped by a dimension. Takes no time window. Arguments 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 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 Returns

​
Recipe — weekly readout

1

Compute the window in epoch seconds

Turn your date range into UNIX epoch seconds (strings) — e.g. last Monday 00:00 → this Monday 00:00.
2

Pull the headline KPIs

get_report_summary(since, until) returns this week plus previous for a week-over-week read.
3

Add the agent leaderboard

get_entity_summary(entity="agent", since, until) for per-agent rows.
4

Snapshot the live board

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.