> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/analytics/openapi.json](/docs/api/analytics/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Analytics: Get campaign engagement

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Analytics](/docs/api/analytics.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## Get campaign engagement

`GET /v1/analytics/engagement` - operationId `analytics.get-engagement`

| Permission | Rate limit |
| --- | --- |
| Campaigns view | 12,000 requests a minute per API key |

Ranks one campaign's clicks on tracked links by a dimension, such as device or country, most clicks first.

`campaignId`, `from` and `to` are required, and the window is at most 366 days.
`dimension` is `device` (the default), `browser`, `os`, `country`, `region`,
`city`, `referrer`, `network`, `link` or `source`. `limit` caps the rows, from 1 to
200, default 50.
The `device`, `browser`, `os`, `country`, `city` and `link` rows count human clicks.
The `region`, `referrer`, `network` and `source` rows count every click and split it into
`humanCount` and `botCount`.
`country` narrows the `city` dimension to one country. `segmentId` narrows the `region`,
`referrer`, `network` and `source` dimensions to one segment.

Errors:

- `400 validation_failed`: `campaignId`, `from` or `to` is missing, the window is too long, or `dimension` or `limit` is not valid.
- `404 not_found`: the campaign is not in the workspace.

Requires Campaigns view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/analytics/GET/v1/analytics/engagement)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `campaignId` | query | integer (int64) | no | The campaign to break down. Required. |
| `from` | query | string (date-time) | no | First day of the window, an ISO 8601 date such as `2026-10-01`. Required. |
| `to` | query | string (date-time) | no | Last day of the window, inclusive, an ISO 8601 date. Required, on or after `from` and at most 366 days later. |
| `dimension` | query | string | no | What to rank by: `device` (default), `browser`, `os`, `country`, `region`, `city`, `referrer`, `network`, `link` or `source`. |
| `country` | query | string | no | Only clicks from this country, for the `city` dimension. Use a `key` from the `country` dimension's rows. |
| `segmentId` | query | integer (int64) | no | Only clicks from this segment of the campaign. Applies to the `region`, `network`, `referrer` and `source` dimensions. |
| `limit` | query | integer (int32) | no | Most rows to return, from 1 to 200. Default 50. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `Engagement`.

| Field | Type | Description |
| --- | --- | --- |
| `campaignId` | integer (int64) | The campaign the clicks belong to. |
| `from` | string (date-time) | The start of the window, in UTC. |
| `to` | string (date-time) | The end of the window, in UTC. |
| `dimension` | string | What the rows split clicks by: `device`, `browser`, `os`, `country`, `city`, `link`, `region`, `network`, `referrer` or `source`. |
| `rows` | array of EngagementRow | One row per value of the dimension, at most `limit`. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/analytics/engagement?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "campaignId": 812,
    "from": "2026-09-23T15:02:11Z",
    "to": "2026-09-23T15:02:11Z",
    "dimension": "device",
    "rows": [
      {
        "key": "string",
        "label": "string",
        "count": 1,
        "humanCount": 1,
        "botCount": 1,
        "uniqueContactCount": 1
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### EngagementRow

The clicks for one value of the dimension.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | no | The value, such as a device type, a country or a link URL. |
| `label` | string | no | A display label for the value. |
| `count` | integer (int32) | no | Clicks. For `device`, `browser`, `os`, `country`, `city` and `link`, human clicks only. For `region`, `network`, `referrer` and `source`, every click. |
| `humanCount` | integer (int32) | no | Human clicks. Only for `region`, `network`, `referrer` and `source`. |
| `botCount` | integer (int32) | no | Clicks from bots and link scanners. Only for `region`, `network`, `referrer` and `source`. |
| `uniqueContactCount` | integer (int32) | no | Distinct contacts who clicked. Only for `region`, `network`, `referrer` and `source`. |
