Skip to main content

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​

ScopePurpose
analytics:readEvery Reporting endpoint
reporting:read_agentsOther people's figures: the full Team report, colleagues' rows in the team workload, and team pages in PDFs
settings:updatePATCH /reporting/settings
reporting:scheduleScheduled report emails (/reporting/schedules)
billing:readAI cost in EUR in the AI report and its exports
campaigns:readMarketing 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 pathReturns
GET /reporting/metaWorkspace timezone, Team tab setting, what the caller may see, plan features, tracking start, SLA targets
GET /reporting/customer-serviceVolume, channels, first response, resolution, backlog and its trend, busiest hours, tags, bot handover, capacity, unassigned wait, reopen rate, working-hours times, SLA
GET /reporting/teamOne row per person: closed, received, answered, messages sent, first response, open now, snoozed now, AI suggestion use, capacity
GET /reporting/aiAI messages by source, bot outcomes, top FAQ entries, low-confidence questions, internal ratings, knowledge base queries, AI cost
PATCH /reporting/settingsTeam tab on or off, SLA targets
POST /reporting/{report}/exportPDF or CSV download
GET /reporting/auditReporting audit log
GET, POST /reporting/schedulesList or create scheduled report emails
GET, PATCH, DELETE /reporting/schedules/{schedule_id}Read, change, pause, resume or delete one
POST /reporting/schedules/{schedule_id}/testSend a test to yourself
GET /analytics/team-workloadLive 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:

ParameterDescription
presettoday, yesterday, last_7d, last_30d (default), last_90d, this_month, previous_month, custom
from, toFirst and last day, YYYY-MM-DD, both inclusive. Giving them without preset means custom. At most 366 days
tzIANA timezone for day boundaries, for example Europe/Berlin. Default: the workspace timezone
compareprevious_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; null when you only see your own row): closed, received, answered, messages_sent, first_response_avg_seconds.
  • AI: ai_messages_total, bot_resolution_rate, kb_queries and, with billing: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"
BlockContents
volumeopened, 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_channelchannel_type, messages_in, messages_out
first_responseavg_seconds, median_seconds, p90_seconds, count: conversations created in the timeframe with a first reply; replies under 5 seconds are left out
resolutionavg_seconds, median_seconds, count: conversations closed in the timeframe, created to closed
backlogSnapshot now: open, snoozed, unassigned, needs_reply, urgent, oldest_waiting_at, unassigned_oldest_waiting_at, generated_at
heatmap168 cells (weekday 0 = Monday, hour 0 to 23, local time) of conversations opened
by_tagTop 20 tags on conversations created in the timeframe: tag_id, name, color, count
by_inboxAlways null in this version
bot_handoverbot_sessions, bot_escalations, rate (0 to 1, null without sessions)
capacitySnapshot now: members_total, ignored_in_routing, capped_members, absent_now
unassigned_waitavg_seconds a conversation waited unassigned (from becoming unassigned or being reopened until someone got it), count, tracking_since
backlog_trendEnd-of-day open, snoozed and unassigned per local day (series[] with date), tracking_since. null when the caller cannot see the whole queue
reopenreopened, closed (in the timeframe), rate (0 to 1), tracking_since
working_hoursconfigured, timezone, and first_response / resolution (avg_seconds, median_seconds, count) counted only inside the workspace business hours. configured is false without business hours
slaconfigured, basis (business_hours or calendar) and, per target, first_response / resolution: target_seconds, met, breached, pending, rate
comparisonSee 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": { "...": "..." } }
}
  • scope is all (every active member, counts over every conversation), visible (every active member, counts limited to the inboxes the caller can see) or self (only the caller's own row: no reporting:read_agents, or the Team tab is switched off).
  • closed counts conversations the person closed or resolved in the timeframe; closes by bots and automations are not attributed to anyone.
  • closed_total is all time. From 19 November 2026 it comes from the daily snapshots, so it no longer shrinks when your retention settings delete old conversations. In visible scope it counts only conversations that still exist.
  • received (conversations assigned to the person), answered (conversations the person replied to), messages_sent and first_response (conversations where the person sent the first human reply, measured from when the conversation was created; avg_seconds, count) are counted from tracking.events_since / tracking.messages_since. They are null when the history is not available, and always null in visible scope (with tracking.received_available false and no comparison for them), because these daily figures are not split by inbox.
  • ai and ai_usage are null on 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.

FieldMeaning
scopeWhat 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
unassignedopen, snoozed; both null when the caller cannot see unassigned conversations
systemCloses by bots and automations (closed_30d, closed_total). Only in the full team view, otherwise null
former_usersopen, snoozed, closed_30d, closed_total of people no longer in the workspace. Only in the full team view, otherwise null
can_view_team_reportWhether 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.

  • cost is only filled with billing:read, otherwise null. It has currency (EUR), total and by_feature[] (feature, amount) with the features assistant, agents, drafts, translation, knowledge_base, builders and other.
  • AI answer details are kept for 90 days. retention.complete is false when the timeframe starts earlier, and retention.answer_events_since says from when they exist.
  • Any block can be null when 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.

reportContentsExtra requirements
customer_service (also customer-service)Customer-service report
teamTeam reportSame rules as GET /reporting/team
aiAI reportPlan with AI features (403 ai_not_available); cost only with billing:read
marketingCampaign performance, subscribers, click-to-WhatsApp ads and tracked linksPlan with campaigns or email campaigns and the campaigns:read scope (403 marketing_not_available)
allCustomer service and team in one PDFPDF 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
}'
FieldRules
name1 to 120 characters
reportsOne or more of customer_service, team, ai, marketing. Each must be on the plan (422 report_not_available)
frequencydaily or weekly
weekdayWeekly only: 0 = Monday to 6 = Sunday
time_of_dayHH:MM in the workspace timezone (shown as timezone)
periodDaily: previous_day. Weekly: previous_7_days (default) or previous_week (Monday to Sunday)
recipient_user_ids1 to 50 user ids of active workspace members. External email addresses are not possible
include_pdfAttach the report as PDF (default true)
statusactive (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 of reporting:schedule can 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_required for 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_agents and the Team tab switched on (recipients[].will_get_team_section), AI cost needs billing:read, the Marketing section needs campaigns:read. Someone who no longer has analytics:read or left the workspace gets nothing.
  • A schedule pauses itself (paused_reason) when its owner leaves the workspace (owner_removed), loses reporting:schedule (owner_lost_scope), the plan no longer includes the reports (plan) or the last recipient unsubscribed (no_recipients). Manual pauses show manual. Resuming an owner_removed or owner_lost_scope schedule (PATCH with "status": "active") makes you its owner.
  • Every email has a one-click unsubscribe link (also as a List-Unsubscribe header) that removes that person from that one schedule. A schedule manager can add them back.
  • last_run_status is sent, partial, failed or skipped. 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.

actiondetails
reporting.team_viewedpreset, from, to, timezone, scope, rows, via
reporting.exportedpreset, from, to, timezone, report, format, included_per_user, locale, via
reporting.settings_updatedOne entry per changed setting (team_tab_enabled, sla) with old and new, plus via
reporting.schedule_createdschedule_id, reports, frequency, recipients, include_pdf
reporting.schedule_updatedschedule_id and changed (field names), or recipient_unsubscribed
reporting.schedule_pausedschedule_id, reason
reporting.schedule_deletedschedule_id, name_length
reporting.schedule_sentschedule_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​

Statusdetail.codeWhen
403reporting_agents_scope_requiredAPI 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)
403ai_not_availableAI export on a plan without AI features
403marketing_not_availableMarketing export without campaigns on the plan or without campaigns:read
403schedule_owner_requiredAn API key or app creates, test-sends or resumes an ownerless schedule
403nothing_to_sendTest send when your permissions allow none of the schedule's reports
404schedule_not_foundThe schedule does not exist in this workspace
403(plan error)The plan has no conversations (API Only)
403reporting_settings_not_allowed_for_appsPATCH /reporting/settings called by an OAuth app
409tenant_settings_unreadableWorkspace settings could not be read; nothing was changed
422invalid_rangeUnknown preset, missing or malformed from / to, or to before from
422range_too_longMore than 366 days
422invalid_timezonetz is not an IANA timezone
422unsupported_formatExport format other than pdf or csv, or csv with report=all
422invalid_slaSLA targets out of range or unknown keys
422invalid_scheduleA schedule field breaks the rules above
422invalid_recipientNo recipients, or a recipient who is not an active member of the workspace
422too_many_recipientsMore than 50 recipients
422too_many_schedulesThe workspace already has 20 schedules
422report_not_availableA scheduled report that is not on the plan
429export_rate_limitedMore than 10 exports in 10 minutes by the same user or API key. Wait Retry-After seconds
429test_send_rate_limitedMore than 5 test sends in 10 minutes
429schedule_rate_limitedMore than 20 new schedules in 24 hours in the workspace
502test_send_failedThe test email could not be sent
503rate_limiter_unavailablePDF export while the export limit cannot be checked. Retry after Retry-After seconds

Reporting errors put code and message inside detail.