Skip to Content
Reporting

Analytics

Campaign and workspace performance, engagement, deliverability and reply classifications, plus your own analytics queries.

Reporting7 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe 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.

Get campaign performance

GET/v1/analytics/campaign-performanceanalytics.get-campaign-performance
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns send, open, click, reply and bounce metrics for one campaign or the whole workspace over a window. The window totals are in metrics, and rows split them by groupBy.

Pass from and to, both inclusive. With campaignId you can leave both out to get the campaign to date: from its first send or first imported day, whichever is earlier, to today, at most 3660 days. The response's from and to hold the window used. A window you set is at most 366 days, or 3660 days with groupBy=campaign. channel is email (the default) or linkedin. The linkedin channel needs campaignId.

groupBy is one of:

  • day (the default): one row per day.
  • step: one row per sequence step. Needs campaignId.
  • segment: one row per segment. Needs campaignId. On email, each row has steps: the segment's email steps in order, each with its sends, contacted, replies, interested replies, bounces and clicks, and one entry per version in variants. Opens and unsubscribes are not split by step and read 0. steps is omitted for a window over 90 days.
  • sender_route: email only, needs campaignId. One row per sender rule a contact's first email went out under: each provider rule (key is the provider, label its name), everyone_else, and not_routed for sends with no rules or with sender routing off. routeKey equals key.
  • language: needs campaignId. One row per language the campaign's emails went out in, sorted by sends, with unknown last for sends that recorded no language. The LinkedIn channel has no language rows.
  • campaign: email only, without campaignId. One row per campaign with email activity in the window, with campaignId on each row.

In sender_route rows, each contact counts in one row only, with its sends, contacted, repliers, interested replies and bounces. Opens, clicks, unsubscribes, bounceBreakdown, opportunities and meetings are not split by route, so they read 0 or are left out on the rows. A language row holds sends, contacted, replies, interested and the reply rate over contacted. A reply counts in the language of the send it answers. Opens, clicks and bounces are not split by language. For both, the window metrics are the campaign's groupBy=day totals, so the rows need not add up to them. A campaign row with a timeZone other than UTC matches that campaign's own groupBy=day read in the same zone, so one call returns lifetime numbers for every campaign. With UTC, the rows add up UTC days, so a contact active on several days counts once per day. campaign rows leave out the opportunity, meeting and bounceBreakdown fields, and the window metrics add up the rows. For per-inbox numbers, call GET /v1/analytics/deliverability with groupBy=inbox.

Days are UTC calendar days unless timeZone is an IANA zone other than UTC. Then rows count that zone's days, from its midnight on from to its midnight after to, and the window metrics add up the day rows. For one campaign, unique opens and unique clicks still count each contact once over the whole window. Imported history and days before 2026-08-24 stay on UTC days. A segment row's opens and unsubscribes also stay on UTC days.

openCount, uniqueOpenCount and openRate count human opens. Opens are an estimate and a floor, so use reply rate as the headline number. clickCount counts human clicks on links Kenso tracks. The opportunity fields appear only when the workspace has the opportunities feature and you have Accounts view.

Errors:

  • 400 validation_failed: the window, groupBy, channel or timeZone is not valid, or the groupBy or channel needs a campaignId.
  • 404 not_found: the campaign is not in the workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalThe campaign to report on. Omitted reports the whole workspace, on the email channel only.
fromquerystring (date-time)optionalFirst day of the window, an ISO 8601 date such as 2026-10-01. Send it with to, or leave both out with campaignId to report the campaign to date.
toquerystring (date-time)optionalLast day of the window, inclusive, an ISO 8601 date on or after from. The window spans at most 366 days, or 3660 days when groupBy is campaign.
groupByquerystringoptionalHow to split the rows: day (default), step, segment, sender_route, language or campaign. Every value except day and campaign needs campaignId, and campaign takes none.
channelquerystringoptionalThe channel to report: email (default) or linkedin. linkedin needs campaignId, and the groupBy values campaign and sender_route work on email only.
timeZonequerystringoptionalIANA time zone whose calendar days the window and day rows use, such as America/New_York. Default UTC.
Request
curl -X GET "https://api.ken.so/v1/analytics/campaign-performance" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a CampaignPerformance.

Show the 8 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get campaign engagement

GET/v1/analytics/engagementanalytics.get-engagement
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalThe campaign to break down. Required.
fromquerystring (date-time)optionalFirst day of the window, an ISO 8601 date such as 2026-10-01. Required.
toquerystring (date-time)optionalLast day of the window, inclusive, an ISO 8601 date. Required, on or after from and at most 366 days later.
dimensionquerystringoptionalWhat to rank by: device (default), browser, os, country, region, city, referrer, network, link or source.
countryquerystringoptionalOnly clicks from this country, for the city dimension. Use a key from the country dimension's rows.
segmentIdqueryinteger (int64)optionalOnly clicks from this segment of the campaign. Applies to the region, network, referrer and source dimensions.
limitqueryinteger (int32)optionalMost rows to return, from 1 to 200. Default 50.
Request
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"

Response 200

data is a Engagement.

Show the 5 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get workspace deliverability

GET/v1/analytics/deliverabilityanalytics.get-deliverability
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the workspace's sending health over a window: sends, replies, bounces, clicks and spam complaints, with inbox and domain counts. Split it by day, by domain or by inbox.

from and to are required, and the window is at most 366 days. groupBy is day (the default), domain or inbox. limit caps the domain and inbox rows, from 1 to 200, default 50. Days are UTC calendar days. With an IANA timeZone other than UTC, the rows count sends, replies, bounces and out-of-office replies on that zone's days, from its midnight on from to its midnight after to. The window sentCount, replyCount, bounceCount, clickCount and rates are then the sums of the day rows. Complaints always stay on UTC days, because Kenso stores them per UTC day.

Domain and inbox rows carry reputation and alerts. Kenso builds the alerts from send pauses, blocklists, SPF, DKIM and DMARC checks, placement tests, complaints and recipient refusals. Inbox rows also get alerts from bounce rates, Microsoft tenant bans and sender rejections, plus their domain's alerts. Reputation and alerts describe the state now: only the complaint_rate and high_bounce_rate alerts count the window.

Errors:

  • 400 validation_failed: from or to is missing, the window is too long, or groupBy, limit or timeZone is not valid.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
fromquerystring (date-time)optionalFirst day of the window, an ISO 8601 date such as 2026-10-01. Required.
toquerystring (date-time)optionalLast day of the window, inclusive, an ISO 8601 date. Required, on or after from and at most 366 days later.
groupByquerystringoptionalHow to split the rows: day (default), domain or inbox.
timeZonequerystringoptionalIANA time zone whose calendar days the window and rows use, such as America/New_York. Default UTC.
limitqueryinteger (int32)optionalMost domain or inbox rows to return, from 1 to 200, default 50. Day rows are not capped.
Request
curl -X GET "https://api.ken.so/v1/analytics/deliverability?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a Deliverability.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get bounce limits

GET/v1/analytics/deliverability-gatesanalytics.get-deliverability-gates
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Shows the bounce limits Kenso enforces, and where each domain and inbox stands against them over the last 24 hours. Use it to spot inboxes close to being blocked.

Kenso counts accepted cold and one-to-one sends and hard bounces over the last 24 hours. It judges inbox rows by the limit that blocks an inbox, and domain rows by the limit that pauses a campaign, because Kenso has no domain-level bounce block. A row's verdict is over when its bounce rate is above threshold with at least minSends sends and minBounces hard bounces. It is watch when the row is not over but its rate is at least 80% of the threshold, and ok otherwise. A row with fewer sends than minSends has isSmallSample true and cannot be over. Kenso itself judges over enforcedWindowHours. isEnforced is false while Kenso only records the limits and does not block or pause. A mailbox with no managed domain counts toward the domain of its address. On a free-mail provider such as gmail.com, it has an inbox row only. Rows come worst first.

Errors:

  • 400 validation_failed: limit is not from 1 to 200.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalThe most domain rows and the most inbox rows to return, from 1 to 200. Default 50.
Request
curl -X GET "https://api.ken.so/v1/analytics/deliverability-gates?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a DeliverabilityGates.

Show the 11 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get reply classifications

GET/v1/analytics/reply-classificationsanalytics.get-reply-classifications
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Counts the people who replied in a window by how Kenso classified their replies. Classes are lowercase snake_case names, such as interested.

from and to are required, and the window is at most 366 days. Replies count by when they arrived, from UTC midnight on from to UTC midnight after to. With an IANA timeZone other than UTC, the window runs from that zone's midnights instead, for the totals and the breakdowns alike. Counts are people, not messages. A contact counts once per row and in one class: interested if any of its messages is, else the class of its latest reply, else the class of its latest message. campaignId and segmentId narrow the counts. byCampaign and bySegment add a breakdown per campaign or per segment.

Errors:

  • 400 validation_failed: from or to is missing, the window is too long, or timeZone is not valid.
  • 404 not_found: the campaign is not in the workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
fromquerystring (date-time)optionalFirst day of the window, an ISO 8601 date such as 2026-10-01. Required.
toquerystring (date-time)optionalLast day of the window, inclusive, an ISO 8601 date. Required, on or after from and at most 366 days later.
campaignIdqueryinteger (int64)optionalOnly replies to this campaign.
segmentIdqueryinteger (int64)optionalOnly replies in this segment.
byCampaignquerybooleanoptionalWhen true, adds a breakdown by campaign. Default false.
bySegmentquerybooleanoptionalWhen true, adds a breakdown by segment. Default false.
timeZonequerystringoptionalIANA time zone whose midnights bound the window, such as America/New_York. Default UTC.
Request
curl -X GET "https://api.ken.so/v1/analytics/reply-classifications" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a ReplyClassifications.

Show the 9 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Run an analytics query

POST/v1/analytics/queryanalytics.query
Permission
Campaigns view
Rate limit
60 requests a minute and 3,000 a day per workspace (Free plan: 6 a minute and 300 a day)
Needs the generative_ui feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Runs a custom report: pick metrics, split them by up to two dimensions, filter them, and compare with the previous period. Use it when the fixed reports do not have the cut you need.

metrics holds 1 to 8 metric names. groupBy holds up to 2 dimensions. filters keeps only the listed values of a dimension. window is a preset, or from and to dates at most 400 days apart. limit caps the rows, from 1 to 200, default 50, and truncated is true when more groups matched. A null dimension value is the Unknown group.

By default (rateBasis event_time), Kenso counts a rate's numerator and denominator by when each event happened, in the same window and group. A rate is then usually from 0 to 1, but can pass 1 in short windows, in day or week rows, or by step, when replies or accepts answer earlier sends. A rate is null when its denominator is 0. With rateBasis cohort, Kenso counts each reply and accept against the send it answers, in that send's group and day, whenever it arrived. Replies, interested, not interested, accepted and their rates then stay within the group's contacted and invites, from 0 to 1. Every row and the totals then carry stillFilling, true while most of their sends are under 7 days old. Other counts use event time on both bases.

With compareTo set to previous_period, Kenso runs the same query over the window of equal length just before, and returns it in previousWindow and in each previous. Rows grouped by day or week usually get previous null, because the earlier window holds other dates, so compare their totals. Each call counts against the workspace's analytics query limit: 60 per minute and 3,000 per day.

Errors:

  • 400 validation_failed: the body breaks a rule above. error.details has one entry per field.
  • 404 not_found: a campaignId filter names a campaign that is not in the workspace.
  • 429 quota_exceeded: the workspace used up its analytics query limit. Retry after Retry-After.

Requires Campaigns view.

Request body

application/json, optional.

FieldTypeRequiredDescription
metricsarray of stringrequiredRequired. 1 to 8 metrics: contacted, sent, delivered, bounced, clicked, replies, interested, not_interested, unsubscribed, meetings, invites, accepted, reply_rate, positive_reply_rate, bounce_rate or acceptance_rate.
groupByarray of stringoptionalUp to 2 dimensions to group rows by: campaign, segment, step, variant, channel, inbox, domain, seniority, function, title_group, industry, company_size, country, week, day or language. Omit it to get only the totals.
filtersmap of objectoptionalValues to narrow the query, keyed by campaignId, segmentId, inboxId, domainId or a dimension name other than week and day. Each key takes a non-empty array of at most 100 values. Ids are numbers or digit strings, channel takes email or linkedin, and other values are strings of at most 200 characters.
windowAnalyticsWindowInputrequiredRequired. The days the query covers: a preset, or a from and to date.
compareTostringoptionalprevious_period to also compute every metric over the window of the same length just before. Omit it to skip the comparison.
timeZonestringoptionalThe IANA time zone for days and weeks, such as Europe/Berlin. Defaults to the campaign's sending time zone when the filters name exactly one campaign, else UTC.
limitinteger (int32)optionalThe most rows to return, from 1 to 200. Default 50.
rateBasisstringoptionalHow replies and accepts are counted. event_time (the default) counts them in the window and group they arrived in, so a rate can pass 1. cohort counts each against the send it answers, with that send's group, so a rate stays from 0 to 1. Every other count uses event time on both bases.
Request
curl -X POST "https://api.ken.so/v1/analytics/query" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "metrics": [
    "contacted"
  ],
  "groupBy": [
    "campaign"
  ],
  "filters": {
    "key": null
  },
  "window": {
    "preset": "last_7_days",
    "from": "2026-09-23",
    "to": "2026-09-23"
  },
  "compareTo": "string",
  "timeZone": "Europe/Berlin",
  "limit": 1,
  "rateBasis": "event_time"
}'

Response 200

data is a AnalyticsQueryResult.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Get variant performance

GET/v1/analytics/variant-performanceanalytics.get-variant-performance
Permission
Campaigns view
Rate limit
60 requests a minute and 3,000 a day per workspace (Free plan: 6 a minute and 300 a day)
Needs the variant_performance feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Compares the variants of each step in one campaign, so you can see which variant wins. The answer has the same shape as POST /v1/analytics/query, with the metrics contacted, replies, interested, reply_rate and positive_reply_rate, grouped by step and variant.

campaignId is required. from and to are inclusive calendar days in timeZone, at most 400 days apart. Leave both out for the campaign to date. timeZone defaults to the campaign's sending zone, else UTC. Each row counts distinct contacts. Replies come from the inbox. Out-of-office replies and other messages that are not replies do not count. Each reply counts against the step and variant of the send it answers, whenever it arrived, so replies and interested stay within contacted and the rates run from 0 to 1. A rate is null when nobody was contacted. Every row and the totals carry stillFilling, true while most of their sends are under 7 days old and replies to them are still arriving. Email and LinkedIn rows both come back. LinkedIn rows read "LinkedIn step N" and "LinkedIn variant X". Contacts with no variant are in the Unknown row. Each call counts against the workspace's analytics query limit: 60 per minute and 3,000 per day.

Errors:

  • 400 validation_failed: campaignId is missing, or the window or timeZone is not valid.
  • 404 not_found: the campaign is not in the workspace.
  • 429 quota_exceeded: the workspace used up its analytics query limit. Retry after Retry-After.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalThe campaign to report on. Required.
fromquerystring (date)optionalFirst calendar day of the window, as YYYY-MM-DD, inclusive. Send it with to, or leave both out to report the campaign to date.
toquerystring (date)optionalLast calendar day of the window, as YYYY-MM-DD, inclusive. The window spans at most 400 days.
timeZonequerystringoptionalIANA time zone the days are counted in, such as America/New_York. Default the campaign's sending time zone, else UTC.
Request
curl -X GET "https://api.ken.so/v1/analytics/variant-performance" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a AnalyticsQueryResult.

Show the 6 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page