# Return engagement over time

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

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

Returns open and click counts and rates bucketed by day, week, or month. Use it to compare
engagement across date ranges and to see how a campaign performed against earlier sends. 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.
    - `tracked_opens` (integer) - The number of messages sent with open tracking on.
    - `tracked_links` (integer) - The number of messages sent with link click tracking on.
    - `opened` (integer) - The number of messages with open tracking that were opened at least once.
    - `clicked` (integer) - The number of messages with link click tracking that had at least one click.
    - `opens_total` (integer) - The number of opens, including repeat opens.
    - `clicks_total` (integer) - The number of link clicks, including repeat clicks.
    - `open_rate` (number, nullable) - Opened messages as a percentage of messages sent with open tracking. `null` when no messages
were sent with open tracking.
    - `click_rate` (number, nullable) - Clicked messages as a percentage of messages sent with link click tracking. `null` when no
messages were sent with link click tracking.

### 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/tracking/timeseries?start=2026-09-01&end=2026-10-30&granularity=week" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```