---
title: "Return engagement over time"
method: GET
path: "/v3/metrics/tracking/timeseries"
tags: ["Tracking events"]
---

# Return engagement over time

`GET /v3/metrics/tracking/timeseries`

## Request

- Base URL: `https://api.us.nylas.com`
- URL: `https://api.us.nylas.com/v3/metrics/tracking/timeseries`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nylas/apis/nylas-api/docs/v3/metrics/tracking/timeseries/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `start` string, date
- `end` string, date
- `sending_domain` string
- `granularity` 'auto' | 'day' | 'week' | 'month'

## Response `200`

Success. Returns one bucket per period.

- object
  - `request_id` string: The request ID.
  - `data` TrackingTimeseries
    - `granularity` 'day' | 'week' | 'month': The bucket size used.
    - `buckets` object[]: One bucket per period in the window, oldest first, including periods with no messages.
      - `start` string, date: The first day in the bucket.
      - `end` string, 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.

## Other responses

- `400`: Bad request. A query parameter or the request body isn't valid.
- `401`: Unauthorized
- `403`: Forbidden. These endpoints need your application's API key, not a grant access token.

## Changes

- **2026-10-30** `7b9fe7c66c1c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nylas/apis/nylas-api/changes/v3/metrics/tracking/timeseries/get.md)

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) - [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nylas/apis/nylas-api/revisions/7782a3e3ab70?raw)