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

# View reports

# View Reports

Access dashboard summaries, email performance metrics, and campaign engagement data using the API.

## Goal

By the end of this guide you will be able to retrieve your dashboard summary statistics, view overall email performance, get time-series histograms, pull detailed reports for individual campaigns, and access engagement breakdowns.

## Prerequisites

* An API key with **`reports:read`** scope
* Your API base URL (found on the Settings > API Keys page)
* At least one sent campaign (for meaningful report data)

## Steps

### 1. Get dashboard summary

Retrieve a high-level snapshot of your email and contact performance over a specified time period.

```bash theme={null}
curl "https://api-us-west-2-c1.benchmarkemail.com/api/reports/dashboard?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Query parameters:**

| Parameter  | Required | Description                                                                       |
| ---------- | -------- | --------------------------------------------------------------------------------- |
| `pastDays` | Yes      | Number of days to look back (1-90)                                                |
| `timezone` | No       | IANA timezone code (default: `UTC`). Example: `America/New_York`, `Europe/London` |

**Response** (`200 OK`):

```json theme={null}
{
  "campaign": {
    "sent": {
      "count": 2379,
      "diff": 0.76
    },
    "delivered": {
      "count": 2203,
      "diff": 11.3
    },
    "uniqueOpens": {
      "count": {
        "value": 733,
        "diff": -23.41
      },
      "rate": {
        "value": 33.27,
        "diff": -22.41
      }
    },
    "uniqueClicks": {
      "count": {
        "value": 569,
        "diff": -21.52
      },
      "rate": {
        "value": 25.83,
        "diff": 20.47
      }
    }
  },
  "contact": {
    "count": {
      "value": 5900,
      "diff": 29.55
    },
    "histogram": {
      "start": "2026-02-28T00:00:00.000Z",
      "end": "2026-03-30T00:00:00.000Z",
      "histogram": [
        { "date": "2026-02-28T00:00:00.000Z", "total": 5420 },
        { "date": "2026-03-07T00:00:00.000Z", "total": 5580 },
        { "date": "2026-03-14T00:00:00.000Z", "total": 5710 },
        { "date": "2026-03-21T00:00:00.000Z", "total": 5850 },
        { "date": "2026-03-28T00:00:00.000Z", "total": 5900 }
      ],
      "peak": {
        "date": "2026-03-28T00:00:00.000Z",
        "total": 5900
      }
    }
  }
}
```

**Understanding the `diff` field:** The `diff` value is a percentage change compared to the equivalent preceding time period. For example, with `pastDays=30`, the diff compares the last 30 days to the 30 days before that. A positive value means an increase; negative means a decrease.

### 2. Get email performance overview

Retrieve aggregate email performance statistics across all campaigns.

```bash theme={null}
curl "https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/overall?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Response** (`200 OK`):

```json theme={null}
{
  "sent": 8450,
  "delivered": 8120,
  "opens": {
    "unique": 2890,
    "rate": 35.59
  },
  "clicks": {
    "unique": 1150,
    "rate": 14.16
  },
  "bounces": {
    "total": 330,
    "hard": 145,
    "soft": 185,
    "rate": 3.91
  },
  "unsubscribes": 42,
  "complaints": 3
}
```

### 3. Get email performance histogram

Retrieve a time-series breakdown of email performance for chart visualization.

```bash theme={null}
curl "https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/overall/histogram?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Response** (`200 OK`):

```json theme={null}
{
  "start": "2026-02-28T00:00:00.000Z",
  "end": "2026-03-30T00:00:00.000Z",
  "histogram": [
    {
      "date": "2026-03-01T00:00:00.000Z",
      "sent": 280,
      "delivered": 268,
      "opens": 95,
      "clicks": 38
    },
    {
      "date": "2026-03-08T00:00:00.000Z",
      "sent": 1250,
      "delivered": 1198,
      "opens": 425,
      "clicks": 170
    },
    {
      "date": "2026-03-15T00:00:00.000Z",
      "sent": 3400,
      "delivered": 3265,
      "opens": 1160,
      "clicks": 465
    }
  ]
}
```

### 4. Get campaign-specific report

Retrieve detailed performance metrics for a single campaign. You will need the campaign ID (from `GET /api/email/campaign`).

```bash theme={null}
curl https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/66f1a6e4698f1bca60426002 \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Response** (`200 OK`):

```json theme={null}
{
  "stats": {
    "sent": 697,
    "delivered": 655,
    "opens": {
      "unique": 210,
      "last": "2026-03-27T17:33:45.464Z",
      "rate": 32.06
    },
    "clicks": {
      "unique": 169,
      "last": "2026-03-27T18:28:40.575Z",
      "rate": 25.8
    },
    "totalBounces": {
      "count": 42,
      "rate": 6.87
    },
    "hardBounces": {
      "count": 25,
      "rate": 3.81
    },
    "softBounces": {
      "count": 17,
      "rate": 2.59
    },
    "unsubscribes": 0,
    "complaints": 0
  },
  "linkActivity": [
    {
      "id": "66f1a6e4698f1bca60424808",
      "path": "https://mybusiness.com/spring-sale",
      "clicks": {
        "total": 145,
        "unique": 120
      }
    },
    {
      "id": "66f1a6e4698f1bca60424809",
      "path": "https://instagram.com/mybusiness",
      "clicks": {
        "total": 38,
        "unique": 32
      }
    }
  ]
}
```

**Key metrics explained:**

* **sent** — Total emails dispatched
* **delivered** — Emails that reached the recipient's mail server
* **opens.unique** — Number of unique recipients who opened the email
* **opens.rate** — Open rate as a percentage of delivered emails
* **clicks.unique** — Number of unique recipients who clicked a link
* **clicks.rate** — Click rate as a percentage of delivered emails
* **totalBounces** — Hard + soft bounces combined
* **hardBounces** — Permanent delivery failures (invalid addresses)
* **softBounces** — Temporary delivery failures (full mailbox, server issues)
* **linkActivity** — Per-link click breakdown

### 5. Get campaign engagement details

Retrieve a time-series engagement histogram for a specific campaign, useful for understanding when recipients interact with your email.

```bash theme={null}
curl "https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/66f1a6e4698f1bca60426002/engagement?period=week&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

**Query parameters:**

| Parameter  | Required | Description                                                |
| ---------- | -------- | ---------------------------------------------------------- |
| `period`   | No       | Engagement window: `24hours` (default), `week`, or `month` |
| `timezone` | No       | IANA timezone code (default: `UTC`)                        |

**Response** (`200 OK`):

```json theme={null}
{
  "start": "2026-03-21T00:00:00.000Z",
  "end": "2026-03-28T00:00:00.000Z",
  "histogram": [
    {
      "date": "2026-03-21T00:00:00.000Z",
      "opens": 145,
      "clicks": 58
    },
    {
      "date": "2026-03-22T00:00:00.000Z",
      "opens": 32,
      "clicks": 12
    },
    {
      "date": "2026-03-23T00:00:00.000Z",
      "opens": 18,
      "clicks": 7
    },
    {
      "date": "2026-03-24T00:00:00.000Z",
      "opens": 8,
      "clicks": 3
    },
    {
      "date": "2026-03-25T00:00:00.000Z",
      "opens": 4,
      "clicks": 1
    },
    {
      "date": "2026-03-26T00:00:00.000Z",
      "opens": 2,
      "clicks": 0
    },
    {
      "date": "2026-03-27T00:00:00.000Z",
      "opens": 1,
      "clicks": 0
    }
  ]
}
```

## Endpoint Summary

| Endpoint                               | Method | Description                               |
| -------------------------------------- | ------ | ----------------------------------------- |
| `/api/reports/dashboard`               | GET    | Dashboard snapshot (campaigns + contacts) |
| `/api/reports/email/overall`           | GET    | Aggregate email performance               |
| `/api/reports/email/overall/histogram` | GET    | Email performance time series             |
| `/api/reports/email/:id`               | GET    | Individual campaign report                |
| `/api/reports/email/:id/engagement`    | GET    | Campaign engagement time series           |

All reports endpoints require `reports:read` scope and accept `pastDays` and `timezone` query parameters (except per-campaign endpoints which use `period`).

## Common Errors

| Status | Error                  | Cause                                                       | Fix                                                                     |
| ------ | ---------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
| `401`  | `UnauthorizedError`    | Invalid or inactive API key                                 | Verify your key in Settings > API Keys                                  |
| `403`  | `ForbiddenError`       | Key lacks `reports:read` scope                              | Create or upgrade your key with `reports:read`                          |
| `400`  | `ValidationError`      | Invalid `pastDays` value (must be 1-90) or invalid `period` | Check query parameters                                                  |
| `404`  | `RecordNotFound`       | Campaign ID does not exist                                  | Verify the campaign ID from `GET /api/email/campaign`                   |
| `429`  | `TooManyRequestsError` | Rate limit exceeded                                         | Wait for the `Retry-After` period. See [Rate Limits](../rate-limits.md) |

## Next Steps

* [Manage Campaigns](./manage-campaigns.md) — create and manage the campaigns you are reporting on
* [Search Contacts](./search-contacts.md) — find contacts for targeted campaign analysis
* [Manage Lists](./manage-lists.md) — manage the lists your campaigns send to