Skip to main content

​
The SLA attestation and report backfill model

Four surfaces answer SLA questions — the tenant-downloadable attestation, the Reliability report in Settings, the service-credit assessment, and the scheduled-reports digest — and they all read the same derivation. This page explains that model once: what an attestation is, why there is exactly one read-model for uptime and delivery-rate math, what the attestation carries that nothing else does, how legacy scheduled reports backfill into their canonical store, and how to reconcile the attestation against your own event stream.

​
What an attestation is

An attestation is a monthly, tenant-viewable statement of SLA truth: one response per calendar month that folds the platform-wide incident summary together with your own delivery and support performance. Any authenticated member of your organization can pull it — it is the org’s own data:
The endpoint is GET /api/v1/reports/sla-attestation; month is the only parameter. The response composes four blocks: Every figure is read live from source-of-truth records — the declared incident feed and your own message and conversation history — with no separate telemetry store behind the endpoint. For a complete month the attestation is reproducible: regenerate it next week and the same inputs return the same figures.

​
The single-read-model rule

Uptime and delivery-rate math exist in exactly one derivation, and every surface that publishes them consumes it:
  • The attestation — the member-accessible summary above.
  • The Reliability report — GET /api/v1/organizations/sla-report, the owner/admin report behind Settings → Reliability, with per-incident detail rows and CSV export.
  • The service-credit assessment — GET /api/v1/organizations/sla-report/credit, which composes the same report with the SLA schedule on your plan.
This was not always the shape. The attestation originally carried its own copy of the formulas, and the two copies disagreed on the same tenant, same month, in two specific ways:
  • Downtime classification. The attestation counted only major and critical incidents as downtime — a minor incident contributed zero minutes — while the Reliability report deducted every minor-inclusive non-scheduled incident minute from the affected channel.
  • The delivery denominator. The attestation divided delivered by delivered + failed; the canonical denominator is the full terminal set (delivered, failed, undelivered, or rejected) — the same status set the analytics dashboard and report summaries divide by. A tenant with 16 delivered, 418 failed, and 22 messages stranded in non-terminal states against a 456-row terminal population read 3.69% on one surface and 3.51% on the other.
A duplicate formula means every published number has to be reconciled before it can be quoted to a customer, and one surface always has to be wrong. The consolidation removed the duplicate: the attestation now hands its incident and delivery inputs to the same derivation the Reliability report and the credit assessment use and winnows the result to the member-safe summary (per-incident detail stays behind the owner/admin gate). The rule the consolidation buys: whichever SLA surface you read, the number is the same number — minor-inclusive downtime, terminal-set delivery denominator, one measured/unmeasured honesty rule.

​
What the attestation carries alone

Two things on the attestation are not delegated to the shared derivation, because they belong to the attestation itself. Support SLA attainment — the support_sla block. Of the digital-channel conversations opened in the window, this is the share that breached neither the first-response nor the resolution SLA, with the breach counts alongside: total_conversations, breached_conversations, and attainment_rate (null when no conversations opened, so an idle month never reads as a misleading 0% or 100%). No other report carries this signal — the Reliability report is availability and delivery only, and voice has its own dedicated surface in GET /api/v1/reports/queue-sla, which measures answer-SLA against queue roll-ups rather than the inbox first-response model. Two scoping rules keep the attainment honest: voice and video conversations are excluded (a call never enters the inbox resolve flow, so it must not drag the digital-channel number), and a first-response breach only counts when an inbound message actually arrived — an agent-initiated thread the customer never replied into cannot false-breach. The month window rules. month accepts a YYYY-MM value and attests that whole calendar month in UTC; a malformed value (2026-4, 2026-13) returns 422. Omit it and the attestation defaults to the most recent complete month — the default download is always a finished, attestable period. The window end is clamped to the present, so a partial current month never claims uptime for time that has not elapsed yet. (The Reliability report answers the same question with the same clamps — its current month is flagged month-to-date.)

​
Report backfill semantics

Backfill is how report truth reaches its canonical store when a tenant’s configuration predates it. The concrete case in orbit today is scheduled reports: tenants who configured recurring report digests before the scheduled-reports store existed kept them as a list inside their organization settings. A boot-time backfill walks organizations in bounded, cursor-paginated pages and moves every legacy entry into the canonical store the GET /api/v1/analytics/scheduled-reports surface now reads and writes. The semantics are the part worth understanding, because they are deliberately conservative:
  • Idempotent. The insert is conflict-free — re-running the backfill writes nothing twice — and each migrated organization is flagged so the next boot skips it. A deploy that restarts the API re-runs the scan harmlessly.
  • Gaps are identified, not assumed. Only organizations that still carry a non-empty legacy list and are not yet flagged are scanned; everything else is left untouched.
  • Recomputed vs preserved. The schedule string (a cron expression or a named cadence) is re-interpreted into the canonical daily / weekly / monthly frequency; anything unrecognized defaults to monthly. An entry without an id receives a fresh one; a missing send format defaults to CSV. Everything else — name, report type, recipients, filters, enabled flag, original creation time — is preserved as configured.
  • Never a boot blocker. A batch that fails falls back to row-by-row inserts so one malformed entry cannot drop an organization’s whole set, and a backfill failure logs a warning without ever taking the API down.
The same doctrine shows up across the reporting surface — the queue-SLA report, the attestation, the Reliability report: derive from source-of-truth records at read time, keep backfills conflict-free and re-runnable, and degrade to an honest empty answer rather than a fabricated one when an input is missing.

​
Reconciling the attestation

What to branch on as an integrator:
  • month + window — attest only against a complete month; a window whose to predates the calendar month end is a partial, still-accruing period.
  • platform_uptime.uptime_percent — a number when at least one channel was measured; treat it alongside downtime_minutes, which is the de-duplicated union of incident minutes, not a naive per-channel sum.
  • channel_delivery[].delivery_rate — null means the channel had no terminal traffic in the window; branch it as “no traffic”, never as 0% or 100%.
  • support_sla.attainment_rate — null means no conversations opened in the window.
To reconcile against your own telemetry, compare like with like. The delivery-rate denominator is your outbound messages reaching a terminal state — accumulate your message-status webhook events per channel, keep only terminal outcomes (delivered, failed, undelivered, rejected), and divide delivered by that set; the figure matches channel_delivery because both sides use the same denominator the analytics pipeline aggregates on. For availability, the inputs are the public declared-incident windows themselves — the same feed the status page publishes — so reconciliation is a comparison against declared facts, not a probe of your own traffic. The operator observability map places each of those telemetry surfaces (webhook stream, analytics aggregates, incident feed) and says which question each answers. When you need the fuller document — per-incident detail rows, CSV export, or the credit assessment for a month that missed its target — the monthly SLA and availability report guide covers the owner/admin surface end to end.