---
title: "List tracking events"
method: GET
path: "/v3/activity/tracking"
tags: ["Tracking events"]
---

# List tracking events

`GET /v3/activity/tracking`

## Request

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

Returns opens and link clicks on your tracked messages, newest first. Filter by message, sender,
label, or event type to see who engaged with a campaign and which links they clicked.

Covers transactional and Agent Account sends that had open or link click tracking turned on.
Events are kept for 90 days, and the default window is the last 7 days.

This endpoint is for looking back at events, not for real-time updates. Avoid polling it for new events. To act on each
open or click as it happens, use [webhook notifications](/docs/v3/agent-accounts/monitor-delivery-engagement/#use-webhooks-for-real-time-events).

## Query parameters

- `event_type` string[]
- `label` string
- `sending_domain` string
- `from` string
- `grant_id` string
- `message_id` string
- `thread_id` string
- `start` integer
- `end` integer
- `order` 'desc' | 'asc'
- `limit` integer
- `page_token` string

## Response `200`

Success. Returns a page of tracking events.

- object
  - `request_id` string: The request ID.
  - `data` object[]: The list of objects returned by the request.
    - `id` string: The ID of the event.
    - `event_type` 'opened' | 'link_clicked': Whether the message was opened or a link in it was clicked.
    - `timestamp` integer: When the open or click happened, as a Unix timestamp in seconds.
    - `application_id` string: The ID of your Nylas application.
    - `grant_id` string: The Agent Account grant that sent the message. Empty for a transactional send.
    - `message_id` string: The ID of the message.
    - `thread_id` string: The Agent Account thread the message belongs to. Empty for a transactional send.
    - `from` string: The email address the message was sent from.
    - `sending_domain` string: The domain the message was sent from.
    - `label` string: The `tracking_options.label` you set when you sent the message.
    - `is_first` boolean: `true` for the first open, or the first click, recorded for the message.
    - `url` string: For a click, the link that was clicked.
    - `link_index` integer: For a click, the position of the link in the message, starting at 0.
    - `ip` string: The IP address the open or click came from. Can be a comma-separated list when the request passed through proxies.
    - `user_agent` string: The user agent of the client that opened the message or clicked the link.
  - `next_cursor` string, nullable: A cursor pointing to the next page of results for the request.

## 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/activity/tracking/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)