> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Metrics Breakdown

> Break your email funnel down by email, sequence, email type, mailbox provider or recipient domain.

Returns the delivery funnel for each value of one dimension, most sends first. Use it to find which email, sequence, mailbox provider or recipient domain is behind a number, then drill into that row by passing its `filter` to [Get Metrics](https://docs.sequenzy.com/api-reference/analytics/metrics.md) or to another breakdown.

Rows count the sends made in the window and the engagement those sends earned, the same way [Get Metrics](https://docs.sequenzy.com/api-reference/analytics/metrics.md) does, so the rows of a complete breakdown add up to its totals. Test sends are excluded, and detected scanners and privacy proxies are excluded unless you set `includeMachineEngagement=true`.

For example, to see which step of a sequence earns its revenue and how it lands at Microsoft:

1. `GET /api/v1/metrics/breakdown?by=sequence` and take the row's `filter.source`, such as `sequence:seq_123`.
2. `GET /api/v1/metrics/breakdown?by=email&source=sequence:seq_123` for each step.
3. `GET /api/v1/metrics/breakdown?by=recipient_domain&source=sequence:seq_123&mailboxProvider=microsoft` to compare Outlook and Hotmail.

## Query Parameters

**by** `string` (default: email)

Dimension to group by: `email` (one row per campaign, sequence email step and
transactional template), `sequence`, `email_type`, `mailbox_provider` or
`recipient_domain`.

**period** `string` (default: 30d)

Sliding window over send times. One of: `1h`, `24h`, `7d`, `30d`, `90d`.
Ignored when `start` and `end` are provided.

**start** `string`

Start of custom time range (ISO 8601). Must be used with `end`.

**end** `string`

End of custom time range (ISO 8601). Must be used with `start`. Max range: 90
days.

**emailType** `string`

Optional structural filter: `campaign`, `sequence`, or `transactional`.
Marketer-role personal keys only see the emails their role can open, and
receive `403` for `transactional`.

**mailboxProvider** `string`

Optional recipient mailbox provider filter, for example `gmail`, `microsoft`,
`yahoo`, or `icloud`.

**recipientDomain** `string`

Optional recipient domain filter, for example `outlook.com`.

**source** `string`

Optional email source filter as `<type>:<id>`: `campaign:<campaignId>`,
`sequence:<sequenceId>`, `sequence_step:<email step id>` or
`transactional:<transactional email id>`. Returns `404` when the source is
not in this company or your key cannot see it.

**limit** `number` (default: 25)

Number of rows to return, from `1` to `100`.

**includeMachineEngagement** `boolean` (default: false)

Set to `true` to include detected scanner, preview, and tracked asset
open/click events.

## Response Fields

**by** `string`

The dimension the rows are grouped by.

**period** `string`

Applied period, or `custom` when `start` and `end` were provided.

**start** `string`

Start of the window the rows cover.

**end** `string`

End of the window the rows cover.

**rows** `array`

One row per dimension value, most sends first. Each row has `key` (the id,
email type, provider or domain; empty when the events predate the column),
`label`, `detail` (for example the sequence an email step belongs to, or
`null`), `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`,
`unsubscribed`, and the rates `deliveryRate` and `bounceRate` (of sent) and
`openRate`, `clickRate` and `unsubscribeRate` (of delivered).

`conversions` and `revenue` (attributed revenue in currency units) count the
orders credited to the row's sends. For `mailbox_provider` and
`recipient_domain`, and with `mailboxProvider` or `recipientDomain` set,
each conversion counts toward the provider and domain of the send it was
attributed to.

`filter` is the filter that narrows a later request to the row:
`{"kind": "source", "source": {"type": "sequence", "id": "seq_123"}}` (pass
it as `source=sequence:seq_123`), `{"kind": "email_type", "emailType":
    "campaign"}`, `{"kind": "mailbox_provider", "mailboxProvider": "gmail"}` or
`{"kind": "recipient_domain", "recipientDomain": "gmail.com"}`. It is `null`
when the row cannot be drilled into, for example an email whose campaign was
deleted.

`emailType`, `mailboxProvider`, `recipientDomain` and `source` are echoed back
when you provide them.

## Errors

| Status | When |
| - | - |
| `400` | Invalid `by`, period, date range, email type, mailbox provider, domain, source or `limit` |
| `401` | Missing or invalid API key |
| `403` | A marketer-role personal key requested `emailType=transactional` |
| `404` | The `source` is not in this company or your key cannot see it |
| `500` | Analytics storage error; retry the request |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.