# Return send metrics over time

> **GET** `https://api.us.nylas.com/v3/metrics/send/timeseries`

Source: https://developer.nylas.com/docs/reference/api/send-events/get-send-timeseries/

Returns sent, delivered, bounced, and complaint counts with bounce and complaint rates, bucketed
by day, week, or month. Use it to chart how your sending changes over a date range and to spot
the day a problem started. A window can cover up to 365 days.

**Authentication:** NYLAS_API_KEY

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `start` | string, format: date | No | The first day of the window, as a UTC date in `YYYY-MM-DD` format. Defaults to six days before `end`, so the default window covers 7 days. A window can cover up to 365 days. |
| `end` | string, format: date | No | The last day of the window, as a UTC date in `YYYY-MM-DD` format. Defaults to today. Today is included as a partial day. |
| `sending_domain` | string, maxLength: 255 | No | Return only data for messages sent from this domain. |
| `granularity` | string, one of: `auto`, `day`, `week`, `month`, default: `"auto"` | No | The size of each time bucket. `auto` picks `day` for windows up to 21 days, `week` for windows up to 92 days, and `month` for longer windows. Weeks start on Monday. |

## Responses

### 200 - Success. Returns one bucket per period.

- `request_id` (string) - The request ID.
- `data` (object)
  - `granularity` (string, one of: `day`, `week`, `month`) - The bucket size used.
  - `buckets` (array) - One bucket per period in the window, oldest first, including periods with no messages.
    - `start` (string, format: date) - The first day in the bucket.
    - `end` (string, format: date) - The last day in the bucket.
    - `sent` (integer) - The number of messages Nylas accepted for delivery.
    - `delivered` (integer) - The number of messages the recipient's mail server accepted.
    - `bounced_hard` (integer) - The number of permanent bounces, such as an address that doesn't exist. Includes recipients on a suppression list.
    - `bounced_soft` (integer) - The number of temporary bounces, such as a full mailbox.
    - `bounced_undetermined` (integer) - The number of bounces the recipient's server didn't classify.
    - `rejected` (integer) - The number of messages Nylas didn't send because they contained a virus or other bad content.
    - `complaints` (integer) - The number of recipients who marked the message as spam.
    - `bounce_rate` (number, nullable) - Hard bounces as a percentage of sent messages. `null` when no messages were sent.
    - `complaint_rate` (number, nullable) - Complaints as a percentage of delivered messages. `null` when no messages were delivered.

### 400 - Bad request. A query parameter or the request body isn't valid.

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 403 - Forbidden. These endpoints need your application's API key, not a grant access token.

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/metrics/send/timeseries?start=2026-10-01&end=2026-10-30&granularity=day" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```