# `bird email stats query` ## Usage ```bash bird email stats query [flags] ``` ## Description Get selected email metrics Select email metrics over a date or instant window, optionally grouped by one dimension with complete time series per group. Events are selected and bucketed by when they occurred, including activity on messages sent earlier. Filters match recorded event context. Unsupported combinations and unavailable history return 422. Follow cursors by replaying the original body and changing its cursor fields; the response period has an exclusive end and must not replace the request end. Use a new idempotency key for each continuation page; reuse a key only to retry the same page. Build the request from flags, a JSON EmailStatsQueryRequest body via --body-file ("-" reads stdin), or both — a flag overrides the matching body field. Run --example to print a ready-to-edit body, or --dry-run to print the resolved request without sending it. Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after. ## Examples ```bash # print the body shape (no credentials needed) bird email stats query --example # the body it prints: ``` ```json { "filters": { "tag": { "name": "campaign" } }, "from": "2026-08-03", "grain": "quarter_hour", "group_by": "sending_domain", "metrics": ["sends_accepted"], "order": "asc", "sort": "sends_accepted", "timezone": "Europe/Amsterdam", "to": "2026-08-16" } ``` ## Options #### Filters | Name | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--from` | Inclusive start, as a calendar date or RFC 3339 instant. Use the same form for from and to. Instants round down to a local quarter-hour; use Z when timezone is supplied. (required; or in --body-file) | | `--to` | Inclusive end. Dates include the whole local day; instants round down to a local quarter-hour and include that quarter-hour. Dates allow up to 365 local days; instants allow up to 720 hours, subject to available history. Preserve this original bound when following cursors. (required; or in --body-file) | | `--timezone` | IANA timezone for dates and bucket boundaries. Defaults to UTC. | | `--metrics ` | Distinct metrics to return. Unselected metrics are absent. Possible values: sends\_accepted, accepted, processed, delivered, bounced, hard\_bounced, soft\_bounced, admin\_bounced, block\_bounced, undetermined\_bounced, complained, deferred, rejected, oob\_bounces, opens, opens\_non\_prefetched, clicks, unsubscribes, unique\_opens, unique\_opens\_non\_prefetched, unique\_clicks, confirmed\_unique\_opens, confirmed\_unique\_opens\_non\_prefetched, effective\_delivered, all\_bounces, delivery\_rate, bounce\_rate, complaint\_rate, deferral\_rate, open\_rate, click\_rate, unsubscribe\_rate, oob\_rate, processing\_p50\_ms, processing\_p95\_ms, processing\_p99\_ms, total\_p50\_ms, total\_p95\_ms, total\_p99\_ms. (required; or in --body-file) | | `--group-by` | Group by this dimension. Omit for a single ungrouped summary with optional series. Possible values: sending\_domain, category, template\_id, tag, recipient\_domain, mailbox\_provider, mailbox\_provider\_region, sending\_ip, ip\_pool\_id, broadcast\_id, country, region, city, agent\_family, os\_family, device\_family, smtp\_error\_code, feedback\_type. | | `--grain` | Time buckets in the requested timezone. Weeks start on Monday; months start on the first day. Half days start at midnight and noon. Edge buckets count events inside the normalized period. Possible values: quarter\_hour, hour, half\_day, day, week, month. | | `--response-schema` | Print the fields this command returns, then exit | #### Pagination | Name | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--sort` | Grouped requests only. Rank groups by this selected metric; defaults to the first metrics entry. Undefined values sort last in either direction. Ties use the dimension value ascending, with null last. Possible values: sends\_accepted, accepted, processed, delivered, bounced, hard\_bounced, soft\_bounced, admin\_bounced, block\_bounced, undetermined\_bounced, complained, deferred, rejected, oob\_bounces, opens, opens\_non\_prefetched, clicks, unsubscribes, unique\_opens, unique\_opens\_non\_prefetched, unique\_clicks, confirmed\_unique\_opens, confirmed\_unique\_opens\_non\_prefetched, effective\_delivered, all\_bounces, delivery\_rate, bounce\_rate, complaint\_rate, deferral\_rate, open\_rate, click\_rate, unsubscribe\_rate, oob\_rate, processing\_p50\_ms, processing\_p95\_ms, processing\_p99\_ms, total\_p50\_ms, total\_p95\_ms, total\_p99\_ms. | | `--order` | Grouped requests only. Defaults to desc. Possible values: asc, desc. | | `--limit ` | Grouped requests only. Maximum groups per page; defaults to 25. Each group retains its complete series. | | `--starting-after` | Grouped requests only. Opaque next\_cursor from the previous response. Mutually exclusive with ending\_before. | | `--ending-before` | Grouped requests only. Opaque prev\_cursor for backward navigation, or refresh\_cursor to read groups before the anchor in the current sort order. Mutually exclusive with starting\_after. | #### Request | Name | Description | | ------------------- | ------------------------------------------------------------ | | `--body-file` | Read the JSON request body from this file; "-" reads stdin | | `--example` | Print a complete example request body, then exit | | `--dry-run` | Print the resolved request without sending it, then exit | | `--idempotency-key` | Deduplication key; a retry with the same key won't act twice | ## Related | Name | Description | | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [`bird email stats by-bounce-code`](/docs/cli/reference/email-stats-by-bounce-code) | Get bounces by SMTP error code | | [`bird email stats by-broadcast`](/docs/cli/reference/email-stats-by-broadcast) | Get statistics by broadcast | | [`bird email stats by-category`](/docs/cli/reference/email-stats-by-category) | Get statistics by category | | [`bird email stats by-client`](/docs/cli/reference/email-stats-by-client) | Get engagement by email client | | [`bird email stats by-complaint-type`](/docs/cli/reference/email-stats-by-complaint-type) | Get complaints by type | | [`bird email stats by-location`](/docs/cli/reference/email-stats-by-location) | Get engagement by location | | [`bird email stats by-mailbox-provider`](/docs/cli/reference/email-stats-by-mailbox-provider) | Get statistics by mailbox provider | | [`bird email stats by-mailbox-provider-region`](/docs/cli/reference/email-stats-by-mailbox-provider-region) | Get statistics by mailbox provider region | | [`bird email stats by-recipient-domain`](/docs/cli/reference/email-stats-by-recipient-domain) | Get statistics by recipient domain | | [`bird email stats by-sending-domain`](/docs/cli/reference/email-stats-by-sending-domain) | Get statistics by sending domain | | [`bird email stats by-sending-ip`](/docs/cli/reference/email-stats-by-sending-ip) | Get statistics by sending IP | | [`bird email stats by-tag`](/docs/cli/reference/email-stats-by-tag) | Get statistics by tag | | [`bird email stats by-template`](/docs/cli/reference/email-stats-by-template) | Get statistics by template | | [`bird email stats daily`](/docs/cli/reference/email-stats-daily) | Get daily sending statistics | | [`bird email stats hourly`](/docs/cli/reference/email-stats-hourly) | Get hourly sending statistics | | [`bird email stats summary`](/docs/cli/reference/email-stats-summary) | Get aggregate email statistics | ## Related resources - [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer) - [Build your first integration](/learn/paths/integration) (course) - [Send your first email](/docs/get-started/send-your-first-email) (docs) [Get an implementation brief](/learn/workspace?topic=api-basics)