Reporting
The Reporting API returns the figures behind the Reporting page in the app: customer-service, per-person team and AI reports for a timeframe (each with a comparison to the previous period), a live team workload snapshot, PDF and CSV downloads, SLA targets, scheduled report emails and the Reporting audit log.
All endpoints are under https://api.sendseven.com/api/v1 and need a plan that includes conversations (Basic, Professional, Scale, Enterprise). On API Only they return 403 with the plan error that every plan-gated endpoint uses.
Required Scopes
| Scope | Purpose |
|---|---|
analytics:read | Every Reporting endpoint |
reporting:read_agents | Other people's figures: the full Team report, colleagues' rows in the team workload, and team pages in PDFs |
settings:update | PATCH /reporting/settings |
reporting:schedule | Scheduled report emails (/reporting/schedules) |
billing:read | AI cost in EUR in the AI report and its exports |
campaigns:read | Marketing export |
reporting:read_agents and reporting:schedule are held by the Owner and Admin roles. They are never added automatically to custom roles or existing API tokens that have analytics:read; add them on purpose. Neither scope can be granted to OAuth apps.
A signed-in user without reporting:read_agents still gets their own figures from the Team report. An API token has no "own" figures: without reporting:read_agents it gets 403 reporting_agents_scope_required on per-person endpoints.
Endpoints
| Method and path | Returns |
|---|---|
GET /reporting/meta | Workspace timezone, Team tab setting, what the caller may see, plan features, tracking start, SLA targets |
GET /reporting/customer-service | Volume, channels, first response, resolution, backlog and its trend, busiest hours, tags, bot handover, capacity, unassigned wait, reopen rate, working-hours times, SLA |
GET /reporting/team | One row per person: closed, received, answered, messages sent, first response, open now, snoozed now, AI suggestion use, capacity |
GET /reporting/ai | AI messages by source, bot outcomes, top FAQ entries, low-confidence questions, internal ratings, knowledge base queries, AI cost |
PATCH /reporting/settings | Team tab on or off, SLA targets |
POST /reporting/{report}/export | PDF or CSV download |
GET /reporting/audit | Reporting audit log |
GET, POST /reporting/schedules | List or create scheduled report emails |
GET, PATCH, DELETE /reporting/schedules/{schedule_id} | Read, change, pause, resume or delete one |
POST /reporting/schedules/{schedule_id}/test | Send a test to yourself |
GET /analytics/team-workload | Live open / snoozed / closed-in-30-days per person, plus unassigned |
Timeframe
/reporting/customer-service, /reporting/team, /reporting/ai and the export take the same query parameters:
| Parameter | Description |
|---|---|
preset | today, yesterday, last_7d, last_30d (default), last_90d, this_month, previous_month, custom |
from, to | First and last day, YYYY-MM-DD, both inclusive. Giving them without preset means custom. At most 366 days |
tz | IANA timezone for day boundaries, for example Europe/Berlin. Default: the workspace timezone |
compare | previous_period (default) adds a comparison block; none leaves it out |
Days run from local midnight to local midnight, so a day can be 23 or 25 hours long around daylight-saving changes. Every report echoes the resolved window:
"timeframe": {
"preset": "last_7d",
"from": "2026-11-13",
"to": "2026-11-19",
"timezone": "Europe/Berlin",
"start_utc": "2026-11-12T23:00:00Z",
"end_utc": "2026-11-19T23:00:00Z",
"hour_aligned": true,
"generated_at": "2026-11-19T10:15:00Z"
}
end_utc is exclusive. hour_aligned is false for timezones that are not a whole number of hours from UTC (for example Asia/Kolkata); hourly-based figures (volume, busiest hours) are then approximate by up to 30 or 45 minutes at the edges.
Comparison With the Previous Period
With compare=previous_period (the default) the customer-service, team and AI reports add a comparison block for the period of the same length directly before the timeframe:
"comparison": {
"from": "2026-11-06",
"to": "2026-11-12",
"kpis": {
"closed": { "current": 214, "previous": 190, "delta_pct": 12.6 },
"first_response_avg_seconds": { "current": 312.5, "previous": 340.0, "delta_pct": -8.1 }
}
}
delta_pct is the change in percent, rounded to one decimal, and null when there is no previous value or the previous value is 0. Comparisons are always team-level; there is never a comparison per person. Keys:
- Customer service:
opened,closed,messages_in,messages_out,first_response_avg_seconds,first_response_median_seconds,resolution_avg_seconds,resolution_median_seconds,bot_handover_rate,reopen_rate,unassigned_wait_avg_seconds,sla_first_response_rate,sla_resolution_rate,wh_first_response_avg_seconds,wh_resolution_avg_seconds. - Team (totals of the rows you can see;
nullwhen you only see your own row):closed,received,answered,messages_sent,first_response_avg_seconds. - AI:
ai_messages_total,bot_resolution_rate,kb_queriesand, withbilling:read,ai_cost_eur.
Tracked History
Some figures come from daily snapshots that SendSeven started recording on 19 November 2026: the unassigned wait, the backlog trend and the reopen rate in the customer-service report, and received, answered, messages sent and first response per person in the team report. They exist from tracking_since (in GET /reporting/meta and in each of those blocks), which is 19 November 2026 or the day the workspace was created, whichever is later. Days before that are not counted.
The snapshots are refreshed every hour, so today's figures for these blocks can lag by up to about an hour. Days are workspace-timezone days, also when you pass another tz.
Customer Service Report
curl "https://api.sendseven.com/api/v1/reporting/customer-service?preset=last_7d" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"
| Block | Contents |
|---|---|
volume | opened, closed, messages_in, messages_out, granularity (hour for a single day, else day) and a zero-filled series. Each bucket_start is a local ISO 8601 time with UTC offset |
by_channel | channel_type, messages_in, messages_out |
first_response | avg_seconds, median_seconds, p90_seconds, count: conversations created in the timeframe with a first reply; replies under 5 seconds are left out |
resolution | avg_seconds, median_seconds, count: conversations closed in the timeframe, created to closed |
backlog | Snapshot now: open, snoozed, unassigned, needs_reply, urgent, oldest_waiting_at, unassigned_oldest_waiting_at, generated_at |
heatmap | 168 cells (weekday 0 = Monday, hour 0 to 23, local time) of conversations opened |
by_tag | Top 20 tags on conversations created in the timeframe: tag_id, name, color, count |
by_inbox | Always null in this version |
bot_handover | bot_sessions, bot_escalations, rate (0 to 1, null without sessions) |
capacity | Snapshot now: members_total, ignored_in_routing, capped_members, absent_now |
unassigned_wait | avg_seconds a conversation waited unassigned (from becoming unassigned or being reopened until someone got it), count, tracking_since |
backlog_trend | End-of-day open, snoozed and unassigned per local day (series[] with date), tracking_since. null when the caller cannot see the whole queue |
reopen | reopened, closed (in the timeframe), rate (0 to 1), tracking_since |
working_hours | configured, timezone, and first_response / resolution (avg_seconds, median_seconds, count) counted only inside the workspace business hours. configured is false without business hours |
sla | configured, basis (business_hours or calendar) and, per target, first_response / resolution: target_seconds, met, breached, pending, rate |
comparison | See Comparison With the Previous Period |
The averages use the same rules as GET /analytics/response-time and GET /analytics/resolution-time, so they match for the same window. Both leave out the test conversations created by the bot and flow testers. Any block can be null when it could not be calculated; show a dash. The backlog follows the caller's inbox visibility (an API token sees everything); the other blocks describe the whole workspace.
Team Report
curl "https://api.sendseven.com/api/v1/reporting/team?preset=previous_month" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"
{
"timeframe": { "preset": "previous_month", "from": "2026-10-01", "to": "2026-10-31", "timezone": "Europe/Berlin", "...": "..." },
"scope": "all",
"rows": [
{
"user_id": "6b1f8a52-1c1e-4b0e-9a57-2d9f3c1e7a10",
"name": "Anna Berger",
"avatar_url": null,
"is_current_user": false,
"closed": 214,
"closed_total": 1893,
"received": 230,
"answered": 221,
"messages_sent": 1204,
"first_response": { "avg_seconds": 312.5, "count": 198 },
"open_now": 7,
"snoozed_now": 2,
"ai": { "suggestions_requested": 40, "suggestions_accepted": 31, "suggestions_sent": 28 },
"ai_usage": [ { "feature": "suggest", "count": 40 } ],
"capacity": {
"max_open_conversations": 15,
"mode": "workspace_default",
"ignore_in_auto_assignment": false,
"absent_now": false,
"absence_days_in_range": 3
}
}
],
"tracking": { "events_since": "2026-11-19", "messages_since": "2026-11-19", "received_available": true },
"comparison": { "from": "2026-09-01", "to": "2026-09-30", "kpis": { "...": "..." } }
}
scopeisall(every active member, counts over every conversation),visible(every active member, counts limited to the inboxes the caller can see) orself(only the caller's own row: noreporting:read_agents, or the Team tab is switched off).closedcounts conversations the person closed or resolved in the timeframe; closes by bots and automations are not attributed to anyone.closed_totalis all time. From 19 November 2026 it comes from the daily snapshots, so it no longer shrinks when your retention settings delete old conversations. Invisiblescope it counts only conversations that still exist.received(conversations assigned to the person),answered(conversations the person replied to),messages_sentandfirst_response(conversations where the person sent the first human reply, measured from when the conversation was created;avg_seconds,count) are counted fromtracking.events_since/tracking.messages_since. They arenullwhen the history is not available, and alwaysnullinvisiblescope (withtracking.received_availablefalseand no comparison for them), because these daily figures are not split by inbox.aiandai_usagearenullon plans without AI features.- Rows are sorted by name. There is no rank.
- Reading other people's rows is recorded in the Reporting audit trail, kept for 12 months.
Team Workload
GET /analytics/team-workload is the live snapshot behind the dashboard card. It takes no parameters and is cached for up to 60 seconds.
| Field | Meaning |
|---|---|
scope | What the caller can see of the queue: all (every conversation), visible (some inboxes) or mine (own conversations) |
rows[] | user_id, name, avatar_url, is_current_user, open, snoozed, closed_30d, closed_total |
unassigned | open, snoozed; both null when the caller cannot see unassigned conversations |
system | Closes by bots and automations (closed_30d, closed_total). Only in the full team view, otherwise null |
former_users | open, snoozed, closed_30d, closed_total of people no longer in the workspace. Only in the full team view, otherwise null |
can_view_team_report | Whether the caller can open the full Team report |
The full team view (every active member, system, former_users) needs scope all, reporting:read_agents and the Team tab switched on. Everyone else gets their own row and unassigned.
open and snoozed match the inbox counters and GET /conversations/dashboard-counts. In the full team view, the sum of rows[].open, unassigned.open and former_users.open equals the workspace total. API tokens need reporting:read_agents for this endpoint.
AI Report
curl "https://api.sendseven.com/api/v1/reporting/ai?preset=last_30d" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"
Needs analytics:read and a plan with AI features (otherwise 403 with the plan error). Blocks: ai_messages (by source: bots, AI agents, suggestions people sent, email auto-replies; translations listed separately), bot_outcomes (resolved by the bot vs handed over), top_faqs, low_confidence (questions the AI could not answer well, contact data masked), ratings (your team's internal ratings of AI answers, not customer satisfaction), kb_queries, cost and retention.
costis only filled withbilling:read, otherwisenull. It hascurrency(EUR),totalandby_feature[](feature,amount) with the featuresassistant,agents,drafts,translation,knowledge_base,buildersandother.- AI answer details are kept for 90 days.
retention.completeisfalsewhen the timeframe starts earlier, andretention.answer_events_sincesays from when they exist. - Any block can be
nullwhen it could not be calculated.
Settings
curl -X PATCH "https://api.sendseven.com/api/v1/reporting/settings" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{ "team_tab_enabled": false }'
Both fields are optional; send only what you change. sla sets the SLA targets used by the sla block:
{
"sla": {
"first_response_target_seconds": 3600,
"resolution_target_seconds": 86400,
"basis": "business_hours"
}
}
Targets are whole seconds (first response 60 seconds to 30 days, resolution 60 seconds to 365 days) or null. basis is business_hours (default: time only counts inside the workspace business hours from Settings > Company info; without business hours it falls back to calendar) or calendar. Send null for both targets, or "sla": null, to switch SLA off. Invalid values return 422 invalid_sla.
Needs settings:update; OAuth apps cannot change it. Returns the same body as GET /reporting/meta. With the Team tab off, everyone, including holders of reporting:read_agents, gets scope self from the Team report, and PDFs leave out other people. The change is recorded in the Reporting audit trail (kept for 12 months).
PDF and CSV Export
POST /reporting/{report}/export takes format=pdf (default) or format=csv and the timeframe and compare parameters.
report | Contents | Extra requirements |
|---|---|---|
customer_service (also customer-service) | Customer-service report | |
team | Team report | Same rules as GET /reporting/team |
ai | AI report | Plan with AI features (403 ai_not_available); cost only with billing:read |
marketing | Campaign performance, subscribers, click-to-WhatsApp ads and tracked links | Plan with campaigns or email campaigns and the campaigns:read scope (403 marketing_not_available) |
all | Customer service and team in one PDF | PDF only |
Campaign and subscriber figures in the marketing export cover the days from the start of the timeframe up to today (at most 365); the export states the number of days.
CSV files are UTF-8 with a byte order mark and Windows line endings, so they open directly in Excel. The team CSV has one row per person; the other reports use a long format with the columns section, metric, dimension, value. Text cells that start with =, +, - or @ get a leading ' so spreadsheets do not run them as formulas. Percentages are rates from 0 to 1.
curl -X POST "https://api.sendseven.com/api/v1/reporting/all/export?format=pdf&preset=last_30d" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-o report.pdf
A PDF response is application/pdf with Content-Disposition: attachment; filename="sendseven-report-<from>-<to>.pdf". It contains the same figures as the JSON reports for the same parameters. Pages with other people's figures are only included under the same rules as the Team report; for all, an API token without reporting:read_agents gets the customer-service part only. Every export is recorded in the Reporting audit trail, kept for 12 months.
The PDF is written in the app language of the user who exports it: English, German, French, Spanish, Portuguese (Portugal), Italian, Polish or Arabic (right to left). Dates and numbers follow that language's format; any other language falls back to English. Exports with an API key or OAuth token are in English and show "API" as the author.
Exports (PDF and CSV together) are limited to 10 per 10 minutes for each user (or API key) in a workspace. The next export answers 429 export_rate_limited with a Retry-After header in seconds; detail.retry_after carries the same value. If the limit cannot be checked for a moment, PDF exports answer 503 rate_limiter_unavailable (retry after Retry-After seconds); CSV exports go ahead.
Scheduled Report Emails
Scheduled reports email a report to workspace members on a fixed rhythm. They need reporting:schedule and a plan with conversations.
curl -X POST "https://api.sendseven.com/api/v1/reporting/schedules" \
-H "Authorization: Bearer <user access token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Monday team review",
"reports": ["customer_service", "team"],
"frequency": "weekly",
"weekday": 0,
"time_of_day": "08:00",
"period": "previous_week",
"recipient_user_ids": ["6b1f8a52-1c1e-4b0e-9a57-2d9f3c1e7a10"],
"include_pdf": true
}'
| Field | Rules |
|---|---|
name | 1 to 120 characters |
reports | One or more of customer_service, team, ai, marketing. Each must be on the plan (422 report_not_available) |
frequency | daily or weekly |
weekday | Weekly only: 0 = Monday to 6 = Sunday |
time_of_day | HH:MM in the workspace timezone (shown as timezone) |
period | Daily: previous_day. Weekly: previous_7_days (default) or previous_week (Monday to Sunday) |
recipient_user_ids | 1 to 50 user ids of active workspace members. External email addresses are not possible |
include_pdf | Attach the report as PDF (default true) |
status | active (default) or paused |
- A workspace can have at most 20 schedules, and at most 20 can be created per 24 hours (429
schedule_rate_limited). Any holder ofreporting:schedulecan change every schedule of the workspace. - Each person gets at most 10 scheduled report emails per day (workspace timezone) across all schedules of the workspace; beyond that they are skipped for that run. Test sends do not count.
- Schedules are owned by a person: create, test-send and resume ownerless schedules while signed in. API keys and apps get 403
schedule_owner_requiredfor those. - A send time that a daylight-saving change skips is sent at the next valid minute; a repeated hour is sent once. A run more than 24 hours late (for example after an outage) is skipped, never sent late, and each period is sent at most once.
- Each recipient gets only what their own permissions allow, checked again at every send: the Team section needs
reporting:read_agentsand the Team tab switched on (recipients[].will_get_team_section), AI cost needsbilling:read, the Marketing section needscampaigns:read. Someone who no longer hasanalytics:reador left the workspace gets nothing. - A schedule pauses itself (
paused_reason) when its owner leaves the workspace (owner_removed), losesreporting:schedule(owner_lost_scope), the plan no longer includes the reports (plan) or the last recipient unsubscribed (no_recipients). Manual pauses showmanual. Resuming anowner_removedorowner_lost_scopeschedule (PATCHwith"status": "active") makes you its owner. - Every email has a one-click unsubscribe link (also as a
List-Unsubscribeheader) that removes that person from that one schedule. A schedule manager can add them back. last_run_statusissent,partial,failedorskipped. The owner gets an email when a run fails or nobody could receive it.- Report emails are service emails and are not billed as messages.
PATCH /reporting/schedules/{schedule_id} takes any of the fields above. DELETE returns {"success": true, "id": "..."}. A schedule that does not exist in the workspace returns 404 schedule_not_found.
POST /reporting/schedules/{schedule_id}/test sends the most recent complete period to your own email address only, with your own permissions. Other recipients and the schedule timing are not affected. The response has success, sent_to, period_from and period_to. At most 5 test sends per 10 minutes per person (429 test_send_rate_limited).
Audit Log
GET /reporting/audit lists who viewed other people's figures, exported reports, changed Reporting settings or created, changed, paused, deleted or sent scheduled reports, newest first. It needs reporting:read_agents and takes page, page_size (up to 100) and action. Entries are kept for 12 months.
action | details |
|---|---|
reporting.team_viewed | preset, from, to, timezone, scope, rows, via |
reporting.exported | preset, from, to, timezone, report, format, included_per_user, locale, via |
reporting.settings_updated | One entry per changed setting (team_tab_enabled, sla) with old and new, plus via |
reporting.schedule_created | schedule_id, reports, frequency, recipients, include_pdf |
reporting.schedule_updated | schedule_id and changed (field names), or recipient_unsubscribed |
reporting.schedule_paused | schedule_id, reason |
reporting.schedule_deleted | schedule_id, name_length |
reporting.schedule_sent | schedule_id, period, status, sent, skipped, failed, team_recipients (how many got the Team section); test sends have test and period only |
Each item has id, action, actor_user_id, actor_name, actor_type (user, api or system), created_at and details. details never contains report figures.
Errors
| Status | detail.code | When |
|---|---|---|
| 403 | reporting_agents_scope_required | API token without reporting:read_agents on the Team report, team workload or a team export. detail.required_scopes lists the missing scope |
| 403 | (scope error) | Missing analytics:read, settings:update, reporting:schedule or reporting:read_agents (audit log) |
| 403 | ai_not_available | AI export on a plan without AI features |
| 403 | marketing_not_available | Marketing export without campaigns on the plan or without campaigns:read |
| 403 | schedule_owner_required | An API key or app creates, test-sends or resumes an ownerless schedule |
| 403 | nothing_to_send | Test send when your permissions allow none of the schedule's reports |
| 404 | schedule_not_found | The schedule does not exist in this workspace |
| 403 | (plan error) | The plan has no conversations (API Only) |
| 403 | reporting_settings_not_allowed_for_apps | PATCH /reporting/settings called by an OAuth app |
| 409 | tenant_settings_unreadable | Workspace settings could not be read; nothing was changed |
| 422 | invalid_range | Unknown preset, missing or malformed from / to, or to before from |
| 422 | range_too_long | More than 366 days |
| 422 | invalid_timezone | tz is not an IANA timezone |
| 422 | unsupported_format | Export format other than pdf or csv, or csv with report=all |
| 422 | invalid_sla | SLA targets out of range or unknown keys |
| 422 | invalid_schedule | A schedule field breaks the rules above |
| 422 | invalid_recipient | No recipients, or a recipient who is not an active member of the workspace |
| 422 | too_many_recipients | More than 50 recipients |
| 422 | too_many_schedules | The workspace already has 20 schedules |
| 422 | report_not_available | A scheduled report that is not on the plan |
| 429 | export_rate_limited | More than 10 exports in 10 minutes by the same user or API key. Wait Retry-After seconds |
| 429 | test_send_rate_limited | More than 5 test sends in 10 minutes |
| 429 | schedule_rate_limited | More than 20 new schedules in 24 hours in the workspace |
| 502 | test_send_failed | The test email could not be sent |
| 503 | rate_limiter_unavailable | PDF export while the export limit cannot be checked. Retry after Retry-After seconds |
Reporting errors put code and message inside detail.