# List tracking events

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

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

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).

**Authentication:** NYLAS_API_KEY

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `event_type` | array | No | Return only these event types. Repeat the parameter to include both. |
| `label` | string, maxLength: 2048 | No | Return only events for messages sent with this `tracking_options.label`. |
| `sending_domain` | string, maxLength: 255 | No | Return only data for messages sent from this domain. |
| `from` | string, maxLength: 320 | No | Return only events for messages sent from this email address. |
| `grant_id` | string, maxLength: 36 | No | Return only events for messages sent by this Agent Account grant. |
| `message_id` | string, maxLength: 512 | No | Return only events for this message. |
| `thread_id` | string, maxLength: 64 | No | Return only events for messages in this Agent Account thread. |
| `start` | integer, format: int64 | No | Return events at or after this time, as a Unix timestamp in seconds. Defaults to midnight UTC six days ago, so the default window covers the last 7 days. Activity is kept for 90 days, so an earlier value returns events from the last 90 days only. |
| `end` | integer, format: int64 | No | Return events at or before this time, as a Unix timestamp in seconds. Defaults to the time of the request. Must not be earlier than `start`. |
| `order` | string, one of: `desc`, `asc`, default: `"desc"` | No | The sort order of the results by event time. `desc` returns the newest events first. |
| `limit` | integer, max: 200, default: `50` | No | The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination) for more information. |
| `page_token` | string | No | An identifier that specifies which page of data to return. You can get this value from the `next_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more information. |

## Responses

### 200 - Success. Returns a page of tracking events.

- `request_id` (string) - The request ID.
- `data` (array)
  - `id` (string) - The ID of the event.
  - `event_type` (string, one of: `opened`, `link_clicked`) - Whether the message was opened or a link in it was clicked.
  - `timestamp` (integer, format: int64) - 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. For a transactional send, this is the message's `Message-ID` header.
  - `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.

### 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/activity/tracking?label=october-newsletter&event_type=link_clicked" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```