An analytics query.

Fields

• metrics (required): Every count is attributed to the time its event occurred, so a message accepted in one bucket can be delivered in the next. Delivery outcomes happen once per recipient, so their event counts equal recipient counts. messages counts accepted messages; mta_accepted and attempted_recipients count recipients the MTA received. Under provider, infrastructure and diagnosis dimensions, sent/attempted count delivery attempts: mta_accepted and attempted_recipients equal delivery_attempts when a query groups or filters by provider_family, provider_subtype, dedicated_ip, dedicated_pool_id, infrastructure_state or an SMTP diagnosis dimension, because the MTA assigns those values at the delivery attempt; the other lifecycle metrics return null there, and a breakdown by those dimensions omits the unknown group. deferred_recipients counts recipients delayed on the first attempt; deferred_events counts every deferral. delivery_attempts counts delivered, deferred and in-band bounced attempts. transport_outcome_recipients = delivered + bounced + soft_bounced. effective_delivered = delivered minus out-of-band bounces in the same period and can be negative for a single bucket or group. Engagement counts per class are unique per recipient, counted when the first qualifying open or click occurred; _events variants count every observation. Rates are fractions; zero denominators return null, and event-time rates can exceed 1. Latency percentiles are milliseconds read from log-scale histograms (error below 15 percent); _samples returns the sample count. Personal message dimensions support daily buckets over the message retention period. delivery_rate = delivered / transport_outcome_recipients. effective_delivery_rate = effective_delivered / transport_outcome_recipients. bounce_rate = bounced / transport_outcome_recipients. deferral_rate = deferred_events / delivery_attempts. complaint_rate = complained / delivered. human_open_rate = human_opens / open_tracked_delivered. human_click_rate = human_clicks / click_tracked_delivered.
• from (optional): Inclusive calendar date or RFC 3339 instant. Default: 30 calendar days including today. Instants are aligned outward to whole UTC hours, or whole UTC days when from_address or subject is grouped or filtered; meta.from, meta.to, meta.effective_to and meta.alignment report the exact window used.
• to (optional): Inclusive calendar date or exclusive RFC 3339 instant. Maximum window: 90 days. Instants are aligned outward to whole UTC hours, or whole UTC days when from_address or subject is grouped or filtered; meta.from, meta.to, meta.effective_to and meta.alignment report the exact window used.
• timezone (optional): IANA time zone. Default: UTC.
• include (optional): Result sections. Default: summary only. breakdown requires group_by, and group_by requires breakdown.
• group_by (optional): Up to three grouping dimensions for breakdown rows. Requires breakdown in include. Default: no grouping.
• filters (optional): Dimension filters combined with AND. Default: no filters. Each metric must support every filter dimension.
• interval (optional): Time-series bucket size. Default: day.
• compare (optional): Compares with the preceding period of the same duration. Omit for no comparison.
• include_trend (optional): Includes trends for breakdown rows. Requires breakdown and group_by. Default: false.
• sort (optional): Optional breakdown sort. Omit to use the default row order.
• limit (optional): Maximum breakdown rows per page. Default: 50; maximum: 200.
• cursor (optional): Repeat the same query with this cursor. It expires within 60 seconds.

Absent fields are :unset; nil is JSON null. extra holds response fields that this version of the SDK does not know.