> ## 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 Sequence Metrics

> Retrieve engagement metrics for a specific sequence, including per-step breakdown and failure details.

Returns aggregate engagement metrics for a sequence (automation) plus a per-step breakdown showing how each email in the sequence performed. Each step also includes recent failed subscribers and their failure reasons. Both aggregate and per-step metrics respect the time filter. Test sends are excluded from these performance metrics and attributed revenue by default so previews do not skew results, but they still count toward send usage and quota. Open and click metrics also exclude detected email-security scanners and tracked brand assets by default.

## Path Parameters

<ParamField path="sequenceId" type="string" required>
  The ID of the sequence.
</ParamField>

## Query Parameters

<ParamField query="period" type="string">
  Sliding time window. One of: `1h`, `24h`, `7d`, `30d`, `90d`. Ignored when
  `start` and `end` are provided.
</ParamField>

<ParamField query="start" type="string">
  Start of custom time range (ISO 8601). Must be used with `end`.
</ParamField>

<ParamField query="end" type="string">
  End of custom time range (ISO 8601). Must be used with `start`. Max range: 90
  days.
</ParamField>

<ParamField query="includeMachineEngagement" type="boolean" default="false">
  Set to `true` to include detected scanner, preview, and tracked asset
  open/click events in engagement metrics.
</ParamField>

## Response Fields

| Field        | Type     | Description                                            |
| ------------ | -------- | ------------------------------------------------------ |
| `sequenceId` | `string` | The sequence ID                                        |
| `stats`      | `object` | Aggregate stats across all steps (same shape as below) |
| `steps`      | `array`  | Per-step metrics, ordered by position                  |

**Stats object** (used for both aggregate and per-step):

| Field             | Type     | Description                                                                                     |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `sent`            | `number` | Emails sent                                                                                     |
| `delivered`       | `number` | Emails delivered                                                                                |
| `bounced`         | `number` | Emails that bounced                                                                             |
| `opened`          | `number` | Unique opens                                                                                    |
| `clicked`         | `number` | Unique clicks                                                                                   |
| `unsubscribed`    | `number` | Unsubscribes                                                                                    |
| `deliveryRate`    | `number` | Delivery rate percentage                                                                        |
| `bounceRate`      | `number` | Bounce rate percentage                                                                          |
| `openRate`        | `number` | Open rate percentage                                                                            |
| `clickRate`       | `number` | Click rate percentage                                                                           |
| `unsubscribeRate` | `number` | Unsubscribe rate percentage                                                                     |
| `conversions`     | `number` | Goal conversions attributed to this sequence (last-touch, 24h window)                           |
| `revenueCents`    | `number` | Attributed revenue in cents from purchase events (`saas.purchase` and `ecommerce.order_placed`) |

The `conversions` and `revenueCents` fields appear on the top-level `stats` object only, not on per-step stats.

**Steps array**:

| Field               | Type           | Description                                           |
| ------------------- | -------------- | ----------------------------------------------------- |
| `step`              | `number`       | Step number (1-indexed)                               |
| `nodeId`            | `string`       | Node ID for this email step                           |
| `subject`           | `string\|null` | Email subject line                                    |
| `stats`             | `object`       | Stats for this step                                   |
| `failedCount`       | `number`       | Number of subscribers that failed at this step        |
| `failedSubscribers` | `array`        | Up to 20 most recent failed subscribers for this step |

**Failed subscriber object**:

| Field          | Type           | Description                            |
| -------------- | -------------- | -------------------------------------- |
| `subscriberId` | `string`       | Subscriber ID                          |
| `email`        | `string\|null` | Subscriber email captured on the token |
| `failedAt`     | `string`       | When the token failed (ISO 8601)       |
| `failedReason` | `string\|null` | Stored failure reason for the token    |

## Common Queries

### How is our onboarding sequence performing overall?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/sequences/seq_abc123" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Check the top-level `stats` for aggregate performance across all steps.

### Which step has the highest drop-off?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/sequences/seq_abc123" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Compare `openRate` across the `steps` array. A sharp drop between consecutive steps signals where subscribers lose interest.

### How many people unsubscribed from the second email?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/sequences/seq_abc123" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Look at `steps[1].stats.unsubscribed` (step 2, zero-indexed in the array). If the unsubscribe rate is high on a specific step, consider revising that email's content or timing.

### How has the sequence performed this month?

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/sequences/seq_abc123?start=2026-02-01T00:00:00Z&end=2026-02-28T00:00:00Z" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Both aggregate and per-step metrics will be scoped to this time range.

### Who engaged with this sequence?

Use the [Get Recipients](/api-reference/analytics/recipients) endpoint with a `sequenceId` filter:

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/recipients?sequenceId=seq_abc123" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "sequenceId": "seq_abc123",
    "stats": {
      "sent": 122,
      "delivered": 120,
      "bounced": 2,
      "opened": 80,
      "clicked": 5,
      "unsubscribed": 1,
      "deliveryRate": 98.36,
      "bounceRate": 1.64,
      "openRate": 66.67,
      "clickRate": 4.17,
      "unsubscribeRate": 0.83,
      "conversions": 4,
      "revenueCents": 27800
    },
    "steps": [
      {
        "step": 1,
        "nodeId": "node_001",
        "subject": "Welcome to our platform",
        "stats": { "sent": 60, "delivered": 59, "bounced": 1, "opened": 40, "clicked": 3, "unsubscribed": 0, "deliveryRate": 98.33, "bounceRate": 1.67, "openRate": 67.8, "clickRate": 5.08, "unsubscribeRate": 0 },
        "failedCount": 0,
        "failedSubscribers": []
      },
      {
        "step": 2,
        "nodeId": "node_002",
        "subject": "Quick tips to get started",
        "stats": { "sent": 44, "delivered": 43, "bounced": 1, "opened": 30, "clicked": 2, "unsubscribed": 1, "deliveryRate": 97.73, "bounceRate": 2.27, "openRate": 69.77, "clickRate": 4.65, "unsubscribeRate": 2.33 },
        "failedCount": 2,
        "failedSubscribers": [
          {
            "subscriberId": "sub_failed_001",
            "email": "failed@example.com",
            "failedAt": "2026-02-14T09:32:11.000Z",
            "failedReason": "Email template ID is required"
          },
          {
            "subscriberId": "sub_failed_002",
            "email": "unknown@example.com",
            "failedAt": "2026-02-14T09:11:42.000Z",
            "failedReason": "Node node_002 not found"
          }
        ]
      },
      {
        "step": 3,
        "nodeId": "node_003",
        "subject": "Your first week recap",
        "stats": { "sent": 18, "delivered": 18, "bounced": 0, "opened": 10, "clicked": 0, "unsubscribed": 0, "deliveryRate": 100, "bounceRate": 0, "openRate": 55.56, "clickRate": 0, "unsubscribeRate": 0 },
        "failedCount": 0,
        "failedSubscribers": []
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Invalid period. Must be one of: 1h, 24h, 7d, 30d, 90d"
  }
  ```

  ```json 401 theme={null}
  { "success": false, "error": "Unauthorized" }
  ```

  ```json 404 theme={null}
  { "success": false, "error": "Sequence not found" }
  ```

  ```json 500 theme={null}
  { "success": false, "error": "Internal server error" }
  ```
</ResponseExample>