# Return engagement by domain or sender

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

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

Returns open and click counts and rates grouped by sending domain or sender address. Use it to
compare engagement across your domains and Agent Accounts. Rows are sorted by the number of
messages sent with open tracking by default.

**Authentication:** NYLAS_API_KEY

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `group_by` | string, one of: `sending_domain`, `agent_account`, default: `"sending_domain"` | No | What to group by. `agent_account` groups by the sender email address. |
| `sort` | string, default: `"tracked_opens:desc"` | No | The sort order, as `<key>:<asc|desc>`. The key is one of `key`, `tracked_opens`, `tracked_links`, `open_rate`, or `click_rate`. |
| `limit` | integer, min: 1, max: 100, default: `25` | No | The maximum number of rows to return. When there are more groups, the rest are combined into one final row with the key `(others)`. |
| `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. |

## Responses

### 200 - Success. Returns one row per group.

- `request_id` (string) - The request ID.
- `data` (object)
  - `group_by` (string, one of: `sending_domain`, `agent_account`) - What the rows are grouped by.
  - `window` (object) - A date window. Both days are UTC dates and both are included.
    - `start` (string, format: date) - The first day of the window.
    - `end` (string, format: date) - The last day of the window.
  - `rows` (array) - One row per group, sorted by `sort`.
    - `key` (string) - The sending domain or sender email address. `(others)` for the combined row.
    - `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.
    - `is_others` (boolean) - `true` for the final row that combines every group past `limit`.

### 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?group_by=agent_account&sort=open_rate:desc" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'
```