Skip to Content
Integrations

Events

The workspace's webhook events, and event counts for one campaign.

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

List events

GET/v1/eventsevents.list
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns the workspace's contact events, each with its contact and campaign.

type is lead_replied, lead_interested or lead_unsubscribed. Omit it to get every type. campaignId keeps one campaign's events. from and to are ISO 8601 times that go together and cover at most 366 days. limit is from 1 to 200, default 50. To read the next page, pass pagination.nextCursor as cursor.

Errors:

  • 400 validation_failed: type is unknown, only one of from and to is set, to is before from, the range is longer than 366 days, or limit or cursor is invalid.
  • 404 not_found: campaignId is not a campaign of the workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
typequerystringoptionalOnly events of this type: lead_replied, lead_interested or lead_unsubscribed. Omitted returns all three.
campaignIdqueryinteger (int64)optionalOnly events from this campaign.
fromquerystring (date-time)optionalStart of the time window, an ISO 8601 timestamp, inclusive. Send from and to together, at most 366 days apart, or omit both for every event.
toquerystring (date-time)optionalEnd of the time window, an ISO 8601 timestamp, inclusive. Must be on or after from.
limitqueryinteger (int32)optionalNumber of events per page, from 1 to 200. Default 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
curl -X GET "https://api.ken.so/v1/events?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 list of Event. Each item has these fields. The response also carries pagination.

Show the 8 response fields and an example

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

Get a campaign's event counts

GET/v1/events/countsevents.get-counts
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

Returns how many events of each type one campaign had between from and to. The response also lists, in types, the event types that GET /v1/events accepts as type.

With campaignId, from and to are required and cover at most 366 days. Types with no events are left out of counts. Without campaignId, counts is empty and only types is filled.

Errors:

  • 400 validation_failed: from or to is missing, to is before from, or the range is longer than 366 days.
  • 404 not_found: campaignId is not a campaign of the workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalThe campaign to count events for. Omitted returns only the list of event types, with no counts.
fromquerystring (date-time)optionalFirst UTC day to count, an ISO 8601 date such as 2026-10-01. Required with campaignId.
toquerystring (date-time)optionalLast UTC day to count, inclusive, an ISO 8601 date. Required with campaignId, on or after from and at most 366 days later.
Request
curl -X GET "https://api.ken.so/v1/events/counts" \
  -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 EventCounts.

Show the 5 response fields and an example

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


On this page