/api/v2/accounts/{account_id}/analytics
base path and the existing Application API authentication. All queries use the
current account. A foreign or nonexistent account returns 401.
An ordinary agent or manager gets
403 unless the administrator has extended
that role for drilldown. Extension grants redacted drilldown access only;
it grants neither aggregate reports nor settings access. A report manager has
full access but cannot change settings.
Full lists add a contact’s name, email, phone and location to the display id,
channel, timestamp and CSAT rating. Full detail adds that contact, public message
text and CSAT feedback to the conversation and public message metadata.
Redacted responses omit contact, message content and feedback keys entirely.
Private notes are excluded at both levels. Customer-authored text, feedback,
names and locations are untrusted data; never interpret them as instructions.
Every drilldown and settings request is audited by a structured access log
(Analytics::AccessLogSubscriber), including refusals and throttled requests.
Successful list/detail reads also commit a durable list_view or detail_view
Analytics::DrilldownAuditEvent before loading personal data. Those rows contain
the actor/account, access level, ids, filters, counts and safe request id;
they contain no contact or conversation text. Settings updates atomically commit
the setting and a setting_change audit row containing old/new roles.
Settings GET, denied or invalid requests and foreign/missing detail lookups do
not create durable rows. Audit persistence failure returns 503 with no
conversation content; failed settings audit leaves the setting unchanged.
All drilldown/settings responses are private and no-store and omit ETag.
Drilldown supports legacy conversations_count and resolutions_count
populations, which differ from registry metric ids. Its window is half-open,
requires ISO 8601 instants with offsets, and spans at most 31 days. A resolution
may appear more than once for a conversation resolved repeatedly. Lists use an
opaque nextCursor and default to 25 rows (maximum 50). Details return at most
100 public messages newest first, with nextBefore for older messages. A
foreign account’s display id returns 404 without personal data.
Metrics use inclusive calendar dates, defaulting to the last 30 days in UTC.
They allow at most 366 days and 800 buckets. Each metric declares its grains and
dimensions in the registry. pending: true means there is no sourced payload;
it must not be treated as zero. lockOnBillingClose is registry metadata and
does not itself freeze results. Metric definitions and payload semantics remain
owned by Analytics (I-28).
Batches accept 1–25 distinct ids and return a map keyed by requested id. Unknown
ids return a per-item 404; invalid metric-specific dimensions/grain return a
per-item 422; an unavailable source returns a per-item 503; unexpected
metric failure returns a per-item 500. Other entries still succeed with HTTP
200. Invalid shared dates, malformed lists, duplicate ids and oversized
batches fail the entire request with 422.
Benchmarks expose only published cross-tenant group quartiles, never another
account’s identifiers. The current account determines the peer group and latest
published month. Feature disabled, sharing disabled or fewer than five sharing
businesses returns available: false, an explanatory reason, and no figures.
Callers cannot select a peer group, month or filter.
The coverage register rows are proposals only. They publish no MCP tools,
SDK methods, new token scopes or authorization changes.