Kenso MCP tools

Analytics analytics

Campaign reports, plus experiments: what Ken noticed in the workspace's campaigns, graded by proof (proven, leaning, hunch, measured, cant_tell). experiments-get reads a finding as text by default; repeat its proof words. experiments-make-default and experiments-undo-default change a live sequence and need confirm=true. load_skill('campaign-diagnosis') has the phrasing rules. How one campaign or the workspace did over dates (sends, replies, positive replies, rates; a daily series is group_by day): get-campaign-performance (from_time, to_time; group_by campaign or day; channel email or linkedin). get-counts only when the request asks for event counts: it counts one campaign's events by event type. A placement test's full results: placement-tests-get with test_id.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through analytics_read and changes through analytics_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: experiments-compare, get, experiments-get, placement-tests-get, get-campaign-performance, get-counts, get-deliverability, get-engagement, get-reply-classifications, get-weekly-report, auto-pauses-list, list, experiments-list, learnings-list, experiments-list-readout-history, experiments-make-default, experiments-undo-default, experiments-unwatch, experiments-update, experiments-watch

experiments-compare

Read. Early access: needs experiments on for the workspace. GET https://api.ken.so/v1/experiments/compare

Query: campaignIds string, format string

Compare two campaigns now, over the days both sent. Text by default. A hunch at most: their leads differ. Nothing is stored; use it when the human asks how two campaigns compare.

GET /api/v1/experiments/compare?campaignIds={a},{b}. Sends Ken-Version 1.1. client_id is
sent as X-Ken-Workspace-Id. Needs Campaigns view. A campaign of another workspace is
not_found.

campaign_ids: exactly two different campaign ids of the workspace. Ken reads them the way
the nightly run reads two campaigns side by side: over the days both sent, the one that
sent first as the baseline, counting companies with an interested reply. Proof is hunch at
most; two that never sent on a shared day are cant_tell with no_overlap in stats.reasons,
and one Ken has nothing to read for (a test campaign, or no email sent through a sequence
step since the day experiments read from) is cant_tell with not_read; its claimText names
the campaign and that day. No AI summary.

format text (default): data {kind, name, campaignIds, windowStart, windowEnd, proof,
bucket, progress, claimText, text}. text starts with the claim, then the proof in plain
words and the counts per side; repeat it in the same words. format json: the same fields
without text, plus arms [{key, label, leads, sends, replies, interested, matured, bounced,
unsubscribed}], stats {estimate, interval, pBetter, verdict, reasons}, confounders and
replies.

get

Read. GET https://api.ken.so/v1/dashboard

Query: limit integer

Return active campaign progress and the pipeline summary. Internal. limit is 1 to 100. Completion is a fraction from 0 to 1.

GET /api/v1/dashboard. Internal. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
limit caps the campaign list. The API default is 50.
completionRate is a fraction from 0 to 1.
Email delivery stays on deliverability, spend stays on usage,
and time series stay on campaign performance.

experiments-get

Read. Early access: needs experiments on for the workspace. GET https://api.ken.so/v1/experiments/{experimentId}

Path: experimentId

Read one finding. Text by default: the readout "As text", with the proof in plain words. format=json returns the finding with its latest readout, canMakeDefault and the arm keys experiments-make-default takes.

format text (default): GET /api/v1/experiments/{experimentId}/readout?format=text. Returns
data {experimentId, readoutId, readoutDate, proof, bucket, claimText, text}. text starts
with the claim, then the proof in plain words, the counts per side next to any lift, what
else changed in the window, and the AI summary, insights and recommendations. Below proven
it never says won, winner, beat, proven, best, caused, significant or the like; repeat it
in the same words. Before the first nightly readout text says there is none yet. Here
bucket is Ken's own read; when a member moved the card, text adds a line naming both.

format json: GET /api/v1/experiments/{experimentId}. Returns the list fields plus isWatching, canMakeDefault (a version test at proven, or a guardrail breach, with no open
default), openDefault (the default not yet undone) and latestReadout {id, readoutDate,
proof, bucket, claimText, arms [{key, label, leads, sends, replies, interested, bounced,
unsubscribed, meetings, placement}], series, stats {estimate, interval, pBetter,
guardrails}, confounders, replies, ai {summary, insights, recommendations, oneThing}}.

Sends Ken-Version 1.1. Needs Campaigns view. A finding of another workspace is not_found.

placement-tests-get

Read. GET https://api.ken.so/v1/placement-tests/{placementTestId}

Path: placementTestId

Show one placement test's full results. Internal. Per seed provider, per sender and per seed placement, errors, the copy sent and earlier tests.

GET /api/v1/placement-tests/{placementTestId}. Internal. Sends Ken-Version 1.1.
Requires Delivery view. A test outside the workspace is not_found.
Returns the list fields plus: type (weekly, on_demand, pre_launch), startedAt, sentCount,
failureReason, senderInboxIds, subject and body (the copy sent, with the sample lead's
variables filled; omitted for tests created before it was stored), counts (inbox,
promotions, other, spam, missing, total), providers (gmail, google_workspace, outlook,
microsoft_365, each with the same counts), senders (each sending mailbox with the same
counts), seeds (one row per seed and sender: masked seed address, provider, senderEmail,
placement, folder, detectedAt), errors (message, at; for example a sender the vendor
refused), and earlierTests (up to 10 earlier tests of the test's own campaign and domain,
newest first, with status and rates; a weekly test shared to another campaign trends with
the campaign that owns it, and an inbox test without a domain has none). Result fields
are omitted until the test completes.
sentCount 0 with errors means the vendor sent nothing. Rates are fractions from 0 to 1.

A Kenso test (provider "kenso") also carries, as soon as it starts:
- verdict: {cause, summary} once complete. Read verdict.summary first and show it as is.
- progress: {planned, sent, read, waiting, failed, finalBy}. finalBy is when the last read is due while
  anything waits (about an hour after the start).
- control (with hasControl): the plain control message's inboxRate, spamRate, categoryRate,
  missingRate, counts and providers. Compare it with the main rates to tell a copy problem from a
  domain problem.
- providers[]: tested (false when the test sent nothing to that provider, not in the seed network yet,
  with zero counts), folders (found messages per folder or tab, such as primary or junk, plus missing),
  authentication ({checked, spfPass, dkimPass, dmarcPass, compauthPass, allPass} over the found messages
  that carry results), microsoft (microsoft_365 only: {scored, bulkHigh, medianBcl, medianScl}), and
  medianArrivalSeconds.
- seeds[]: seed (masked such as j***@n***.co; Kenso staff see it in full), arm (main or control), status
  (waiting, found, missing, send_failed or read_failed), tab (the folder or tab, such as primary,
  promotions or junk), placement (pending while not read yet), authentication ({spf, dkim, dmarc,
  compauth}: pass, fail, softfail, none and the like), microsoft ({scl, bcl, cat, sfv} on Microsoft 365
  seeds), arrivalSeconds and detectedAt.

get-campaign-performance

Read. GET https://api.ken.so/v1/analytics/campaign-performance

Query: campaignId integer, channel string, from date-time, groupBy string, timeZone string, to date-time

Return campaign or workspace performance for a window, or one campaign to date. Public. Rates are fractions from 0 to 1. group_by is day, step, segment, sender_route, campaign, or language.

GET /api/v1/analytics/campaign-performance. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
from_time and to_time are sent as from and to. Leave both out with
campaign_id for the campaign to date: from its first send or first imported
day, whichever is earlier, to today, in time_zone's days (default UTC), at
most 3660 days; data.from and data.to hold the window used. Without
campaign_id both are required (group_by campaign always needs them).
Day buckets are UTC days unless
time_zone is an IANA zone that is not UTC: then email day rows (group_by day),
their meetings and opportunity cohort count that zone's calendar days, from its
midnight on from to its midnight after to, and the window metrics add up the rows
(for one campaign, unique opens and unique clicks are the campaign window's, as
without a zone). Opens, unique opens and unsubscribes count that zone's days too.
Imported history and days before 2026-08-24 stay on UTC days: imported history
arrives as date-only day buckets with no time of day to move. Step, segment and
sender_route rows, language rows and the linkedin channel count the window from
the zone's midnights too
(a segment row's opens and unsubscribes stay on their stored UTC days).
channel is email or linkedin. group_by inbox belongs on deliverability.
A campaign outside the workspace is not_found.
group_by sender_route (email, campaign_id required) splits the campaign by the
sender rule each contact's first email went out under: one row per provider
rule (key the provider slug, label its name), everyone_else (the Everyone else
rule) and not_routed (sent with no rules or with sender routing off, so every
send from before routing). Each row also carries routeKey, equal to key. A
contact stays in one row; its sends, contacted, distinct repliers (replyCount),
interestedCount and bounces in the window count there. Opens, clicks,
unsubscribes and bounceBreakdown are not split by route (0 or absent on the
rows). The window metrics are the campaign's group_by day ones, opens and
clicks included, so the rows need not add up to them: a contact with no
accepted send is in no row.
group_by campaign (email, no campaign_id, a window up to 3660 days) returns one
row per campaign with email activity in the window, each with campaignId, in
one call: a row's counts equal the window metrics of that campaign's own
group_by day read with the same non-UTC time_zone. Without a time_zone (or
with UTC) the rows add up UTC days, while the campaign's own read counts
contacted and replies once across the window, so there a contact active on
several days counts once per day. Use it for
every campaign's lifetime numbers at once (from = the oldest campaign's
creation day). On those rows uniqueOpenCount adds up the campaign's days,
uniqueClickCount counts each human clicker once over the UTC window (as the
campaign's own read does), and the opportunity, meetings and bounceBreakdown
fields are absent; the window metrics add up the rows.
Email clicks with group_by day (window metrics and day rows): clickCount is
Kenso-tracked human click events (one contact clicking 3 times counts 3),
uniqueClickCount is unique human clickers, botClickCount is bot and scanner
clicks and is not in clickCount. Use the returned clickRate rather than
recomputing it. group_by step rows carry the step's raw click volume and
uniqueClickCount 0 (unique clickers are not on step rows). Since 15 Nov 2026 an
email sent as plain text carries no click-tracking link and counts no clicks:
a campaign with Send as plain text on has no clicks from then on, except on a
step that keeps its HTML, so read its clicks as not tracked, never as 0 interest.
clicksTracked (beside opensTracked, on the same metrics and left out in the
same places, see opensTracked below) says this for you: false means the
campaign has Send as plain text on. Never report its clickCount or clickRate
as a real number or as zero and never judge a copy, a step or the campaign by
it: say clicks are not tracked. A non-zero count there is partial (a step kept
as HTML: a drawn letter, a Studio render, a video, a provider-built message or
an image; or clicks from before 15 Nov 2026): report it as partial, with no
rate. true means Kenso tracks clicks, including on a campaign on provider
tracks that sends plain text only to its Google leads. Absent on a campaign's
own totals or row means clicks are partly tracked or unknown: the workspace is
past its billing grace (its emails carry no click link from then on), the
campaign was imported and sends as plain text (its imported clicks are the
vendor's), or the read failed; read clickRate there as a floor.
clicksTracked does not show Track link clicks off (trackClicks false on the
campaign read, which applies where the workspace has the campaign_send_settings
flag on): such a campaign records no clicks either, so check trackClicks before
reading a 0.
Open tracking is locked off since 13 Nov 2026: no campaign email carries an
open pixel from then on, so the open fields below count only opens recorded
before that date (or imported from another tool) and gain none after it.
Never report them as a result (deliverability rule 1: opens are not tracked
and are never reported).
Email opens: openCount, uniqueOpenCount and openRate count human opens only.
machineOpenCount (window metrics and group_by step rows; absent elsewhere)
counts contacts whose every open was a machine open: Apple Mail Privacy
Protection, a crawler, or an open within a minute of the send (Gmail and
security-scanner prefetch). Opens only exist for campaigns with Track opens on
(trackOpens). With Send as plain text on (sendAsPlainText, from the campaign
read), most steps go out as text with no pixel, so their opens are missing, not
zero; a step kept as HTML (a drawn letter, a Studio render, a campaign image or
video, a provider-built message) can still carry the pixel, so the campaign's
opens are partial at best. Never report such a campaign's open rate as a real
rate and never judge a copy, a variant or the campaign by it; say opens are
not reliably tracked and use reply rate.
opensTracked (window metrics, rows, and a segment row's steps and versions for one
campaign, and each group_by campaign row) says this for you: false means the
campaign sends as plain text or has Track opens off (or the workspace's send
settings are off), so do not read its openRate as real. With plain text opens are
partial, not none (a step kept as HTML can still carry the pixel); with Track
opens off they are none, apart from opens imported from another tool, which are
the vendor's own. true means Kenso tracks opens. Absent on a campaign's own
totals or row (a one-campaign read, or a group_by campaign row) means opens are
partly tracked or unknown: the workspace is past its billing grace (its emails
carry no pixel from then on, its earlier ones did), the campaign was imported
(its opens are the vendor's own, wherever its settings would say false), or the
read failed. Read openRate there as a floor, never as a real rate or as zero.
It reflects the campaign's
settings now, not at send time: a campaign switched to plain text part way
through reads false for its earlier HTML days, and one switched back reads true
for its plain-text days, so be careful with a window that spans a settings
change. language and sender_route rows leave it out (they split no opens).
A figure that spans campaigns (the window totals, and every row of a read with no
campaign_id other than group_by campaign rows) has no value of its own and is
unknown: check the group_by campaign rows, or one campaign's read, before leaning
on its opens. sendAsPlainText on the campaign read does not show past billing
grace or an import, so it is not enough on its own.
Treat opens as an estimate and a floor (image blocking hides real opens and
not every machine open can be told apart), never the headline metric: reply
rate is. group_by step rows carry the step's human and machine openers; there
the window metrics' openCount adds up the opened step emails and
uniqueOpenCount counts each human opener once.
bounceBreakdown is {hardCount, softCount, unknownCount, byReason}, with
byReason holding non-zero camelCase reasons (invalidRecipient,
policyBlocked, ...). It is on the window metrics and segment rows, comes
from categorized bounce events, and can sum lower than bounceCount;
bounceCount and bounceRate stay the headline. It is omitted when no
categorized split is available, which does not mean zero bounces.
Opportunities (email channel, every group_by except segment, sender_route and
language): opportunitiesCreated, pipelineAmount, wonAmount and wonCount are on the
window metrics and on each day and step row. They are a cohort: the opportunities
created in the window (by their created_at day, see time_zone above) from the
campaign, or from any campaign when campaignId is not set, with their open amount
now (pipelineAmount) and their won amount and count now (wonAmount, wonCount), in
the workspace currency. Step rows key on the campaign step order the opportunity
came from; an opportunity with no step counts in the window metrics only. Segment,
sender_route and language rows and the linkedin channel leave them out, and so does
a workspace with Opportunities off.
Meetings booked (email channel, every group_by except segment, sender_route and
language): meetingsBooked is on the window metrics and on each day and step row. It
counts Scheduler bookings from a campaign step, a reply or a single-use link, once
per booking however often it was rescheduled, plus bookings the reply agent made,
by the day the meeting was booked (UTC, or the time_zone's day as above). Cancelled
bookings do not count; no-shows do. Step rows key on the step the booking came
from; a booking with no step counts in the window metrics only.
group_by language (needs campaign_id) returns one row per language the
campaign's emails went out in, keyed by that language (fr-FR, en, ...), sorted
by sentCount, with the unknown row last: sends that recorded no language,
which is every send before 2026-10-29. A row carries sentCount,
contactedCount, replyCount and interestedCount (distinct contacts) and
replyRate over contacted. A reply counts in the language of the send it
answers, else of the contact's latest earlier email in the campaign. Opens,
clicks and bounces are not split by language (0 on these rows), and the
opportunity and meetings fields are absent. The window metrics are the
campaign's, as group_by day reports them: a contact emailed in two languages
counts once there, so the rows can add up to more. The linkedin channel
returns no language rows.
LinkedIn step rows (channel linkedin, group_by step) also carry variants
[{variant a-d, sentCount, acceptedCount, replyCount, failedCount, acceptRate}]
and the AI note counts notesWaiting, notesSkippedFreeAccount, notesFailed
(0 unless the step is a connection request). Row key is the step's A-version id.
Email segment rows (group_by segment) also carry steps [{stepOrder, metrics,
variants [{variant a-d, metrics}]}]: each email step of the segment and each of
its versions, with sentCount, deliveredCount, bounceCount, contactedCount,
replyCount, interestedCount, clickCount and uniqueClickCount; opens and
unsubscribes are not split by step (0). steps is absent for a window over 90 days.

get-counts

Read. GET https://api.ken.so/v1/events/counts

Query: campaignId integer, from date-time, to date-time

Return the public event type catalog and, with a campaign, its counts. Public. A campaign window requires from and to.

GET /api/v1/events/counts. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
Without campaign_id the response is the public type catalog.
With campaign_id, from and to are required and counts are for that campaign.
Contact events stay on GET /api/v1/contacts/{contactId}/events.

get-deliverability

Read. GET https://api.ken.so/v1/analytics/deliverability

Query: from date-time, groupBy string, limit integer, timeZone string, to date-time

Return workspace deliverability for a reporting window. Public. Rates are fractions from 0 to 1. group_by is day, domain, or inbox.

GET /api/v1/analytics/deliverability. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
from_time and to_time are sent as from and to. Day buckets are UTC days. With a
time_zone that is not UTC, day, domain and inbox rows count sequencer sends,
replies, bounces and out-of-office replies on that zone's days, from its midnight
on from to its midnight after to, and the window sentCount, replyCount,
bounceCount, clickCount and rates are the sums of the day rows. Complaints are
kept per domain per UTC day with no time of day, so they stay on UTC days.
Clicks carry no sending inbox, so delivery rows hold none to move.
limit caps domain and inbox rows from 1 to 200. The API default is 50.
Domain and inbox rows also carry oooCount and oooRate (out-of-office
auto-replies, never counted in replyCount). Day rows leave them null.
metrics.complaintCount is spam complaints in the window (feedback-loop
reports) and metrics.complaintRate is complaintCount / sentCount (omitted
when nothing was sent). Day and domain rows carry complaintCount; inbox
rows omit it. Both are omitted when the complaint data cannot be read.
Domain and inbox rows carry reputation and alerts; day rows omit both.
reputation is paused (an enforced send pause covers the row), at_risk (a
critical alert), watch (a warning alert), unknown (a signal could not be
read, or a domain has no recent check and sent nothing) or good. Each alert
has code, scope (domain or inbox), severity (warning or critical), message
and action (plain sentences to show a user), and since, until (pauses only),
rate and threshold (fractions) when known. Codes: sending_paused,
blocklisted, authentication_failing, dmarc_failing, placement_spam,
placement_low_inbox, complaint_rate (domain rows only), recipient_refusals,
and on inbox rows high_bounce_rate, microsoft_tenant_ban and
sender_rejections. An inbox row also carries its domain's alerts with scope
domain. New codes may be added. Observe-only send blocks never alert.
reputation and alerts describe the state now; only complaint_rate and
high_bounce_rate count the from/to window. Where domain health is on for
the workspace, domain and inbox rows also carry domainHealth: the
domain's health rung, reason, message and action, as health on
domains(operation="get"). It is omitted otherwise and on day rows.

get-engagement

Read. GET https://api.ken.so/v1/analytics/engagement

Query: campaignId integer, country string, dimension string, from date-time, limit integer, segmentId integer, to date-time

Return a ranked engagement breakdown for one campaign. Public. dimension defaults to device on the API. limit is 1 to 200.

GET /api/v1/analytics/engagement. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
from_time and to_time are sent as from and to.
dimension is device, browser, os, country, region, city, referrer, network, link, or source.
country filters the city dimension. segment_id filters region, network, referrer, and source.
A campaign outside the workspace is not_found.

get-reply-classifications

Read. GET https://api.ken.so/v1/analytics/reply-classifications

Query: byCampaign boolean, bySegment boolean, campaignId integer, from date-time, segmentId integer, timeZone string, to date-time

Return reply classification counts for a reporting window. Public. Names are lowercase snake_case. Breakdowns are optional booleans.

GET /api/v1/analytics/reply-classifications. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
from_time and to_time are sent as from and to. Replies count by the day they
came in (created_at), from UTC midnight on from to UTC midnight after to, unless
time_zone is an IANA zone that is not UTC: then from that zone's midnight on from
to its midnight after to, totals and breakdowns alike.
Optional campaign_id must belong to the workspace.
by_campaign and by_segment add those breakdowns. There is no breakdown or
filter by sending configuration: replies are not attributed to one.
Counts are people, not messages: each contact counts once per row, in one
class (interested if any of its messages is, else its latest reply's class,
else its latest message's), so interestedCount is the positive replies.

get-weekly-report

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/weekly-report

Path: campaignId

Query: timeZone string, weekOf string

Return one campaign's weekly report: week and to-date email KPIs, segments, what changed, what is next. Read-only, no AI and no credits. A cross-workspace id is not_found.

GET /api/v1/campaigns/{campaignId}/weekly-report. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.

week_of is any date (YYYY-MM-DD, 2000-01-01 to one year from today) in the wanted
Monday-to-Sunday week. time_zone is an IANA name; without it the campaign's sending
time zone is used, else UTC. The week's dates are picked in that time zone; its
numbers and changed are counted on those UTC days, like the Analytics tab. Without
week_of the report covers the latest week that has ended both there and in UTC.

Returns data {campaignId, campaignName, timeZone, week, toDate, segments, changed, next}.
week and toDate are {startDate, endDate, sentCount, contactedCount, replyCount,
interestedCount, bounceCount}: email counts from campaign performance (they match
analytics get-campaign-performance). interestedCount is positive replies. toDate
runs from the campaign's creation (at most 366 days back) to the end of the week.
segments are to date: {segmentId, name, contactCount, sentCount, replyRate},
replyRate a fraction from 0 to 1.
changed is newest first, at most 6: {kind, occurredAt, segmentId?, text}, kind one of
sequence_version_saved, linkedin_sequence_version_saved, variant_paused,
variant_resumed, segment_added, leads_held_back (one line: the week's leads stopped
for 1:1 account plays, dated by the last stop); text gives the change's UTC day.
Campaign pause and resume are not listed (the external approval pause and resume are
not recorded).
next is {kind, segmentId?, remainingCount?, finishDate?, text}: one
campaign_remaining line (remainingCount for the whole campaign; finishDate, when one
can be estimated, is the day the last lead starts at the last 7 days' pace), then
segment_remaining per segment with leads not started (segmentId, remainingCount, no
date); or a single campaign_paused, campaign_error, campaign_completed or
campaign_archived line. next is as of now (the campaign's sending time zone) and is
empty when week_of names a week older than the default week. Tolerate kinds not
listed here.

auto-pauses-list

Read. GET https://api.ken.so/v1/auto-pauses

Query: cursor string, limit integer, since date-time

List the inboxes, domains, campaigns and workspace holds Ken paused on its own, newest first. Public. isActive is true while the target is still blocked or paused.

GET /api/v1/auto-pauses. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
Lists pauses that started at or after since (ISO-8601 instant; default
7 days ago, older values read as 30 days back) plus any older pause that
is still active. A renewal of a block still in force is the same pause.
Only pauses Ken enforced are listed, so the list is often empty.
limit is 1 to 200 (API default 50) and cursor continues the page.
Item fields: id (opaque string), scope (inbox, domain, campaign or
workspace; a domain pause blocks its inboxes, not campaigns; a workspace
pause blocks every inbox of the workspace until Kenso support releases it),
reason (snake_case code: mailbox_hard_bounce_rate, campaign_hard_bounce_rate,
domain_complaint_rate, domain_gmail_spam_rate, domain_placement_spam,
reply_ingest_dead, uri_blocklist_listed, domain_dns_unresolvable,
tenant_ban (the mailbox's Microsoft 365 tenant refuses to send),
mailbox_sender_ndr_rate, workspace_breaker (the workspace send hold) or
send_failures; new codes may be added),
metric (bounce_rate, complaint_rate, gmail_spam_rate, sender_ndr_rate
or dns; other only for a code added later; omitted when no rate drives
the reason: tenant_ban, reply_ingest_dead, uri_blocklist_listed,
domain_placement_spam, workspace_breaker, send_failures), rate and
threshold (fractions, omitted when the signal has none), domainId,
domainName, inboxId, inboxEmail, inboxCount, campaignId, campaignName,
createdAt, blockedUntil (omitted for a campaign, which stays paused until
resumed; a workspace hold is renewed until released) and isActive.

list

Read. GET https://api.ken.so/v1/events

Query: campaignId integer, cursor string, from date-time, limit integer, to date-time, type string

List workspace webhook events. Public. type is lead_replied, lead_interested, or lead_unsubscribed.

GET /api/v1/events. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view.
from_time and to_time are sent as from and to. Supply both or neither.
Contact events stay on GET /api/v1/contacts/{contactId}/events.

experiments-list

Read. Early access: needs experiments on for the workspace. GET https://api.ken.so/v1/experiments

Query: bucket string, campaignId integer, cursor string, kind string, limit integer, status string

List what Ken noticed in the workspace's campaigns, with the summary bar and the one thing to do today. Each finding has a proof level (how sure Ken is) and a bucket. Read one with experiments-get.

GET /api/v1/experiments. Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id.
Needs Campaigns view. 404 while the experiments flag is off for the workspace.

Filters: status (comma = OR: active, dismissed, archived; default active), bucket
(working, not_working, too_early), kind (version_test, edit, duplicate, two_campaigns,
segment, step, delivery, campaign), campaign_id. limit 1 to 200 (default 50). Pass
pagination.nextCursor back unchanged as cursor while pagination.hasMore is true.

Returns data (findings, oldest first), pagination, summary {working, notWorking,
tooEarly} (active findings per effective bucket under the kind and campaign_id filters)
and oneThing {experimentId, name, text, readoutId, readoutDate}, the one thing to do
today (omitted when there is none, or a member moved that finding). Each finding: id,
kind, name, detectedName, customName, status, proof (proven, leaning, hunch, measured,
cant_tell), bucket, detectedBucket, bucketOverride, bucketOverriddenAt,
bucketOverriddenBy, campaignIds, sequenceId, stepOrder, windowStart, windowEnd,
progress, arms [{key, label, variant, stepIds}], claimText (the latest readout's one
line), latestReadoutId, latestReadoutDate and the dismissed and renamed fields. bucket
is the effective one: bucketOverride when a member moved the card, else detectedBucket
(Ken's own read); the bucket filter uses it too. Say what a finding means in its proof
words: see the campaign-diagnosis skill (load_skill('campaign-diagnosis')).

learnings-list

Read. Early access: needs experiments on for the workspace. GET https://api.ken.so/v1/learnings

List the workspace's learnings: ideas that held across findings. Always empty until Phase 3.

GET /api/v1/learnings. Sends Ken-Version 1.1. Needs Campaigns view. 404 while the
experiments flag is off. Each learning: id, statement, status, testCount,
isInKnowledge and evidence [{experimentId, proof}]. Learnings come with Phase 3
(DEV-1946); until then data is an empty list, so do not report it as "no learnings
found" about the campaigns.

experiments-list-readout-history

Read. Early access: needs experiments on for the workspace. GET https://api.ken.so/v1/experiments/{experimentId}/readout/history

Path: experimentId

Query: cursor string, limit integer

List a finding's past readouts, newest day first: how the proof and numbers moved.

GET /api/v1/experiments/{experimentId}/readout/history. Sends Ken-Version 1.1. Needs
Campaigns view. limit 1 to 200 (default 50); pass pagination.nextCursor back as cursor
while pagination.hasMore is true. Each readout has the latestReadout fields of
experiments-get with format json.

experiments-make-default

Write. Early access: needs experiments on for the workspace. POST https://api.ken.so/v1/experiments/{experimentId}/default

Path: experimentId

Body (json): armKey string

Keep one version of a tested email and turn the email's other active versions off. Needs confirm=true. Only on a version test at proven, or when a guardrail fired on another version. Undo with experiments-undo-default.

POST /api/v1/experiments/{experimentId}/default. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Needs Campaigns edit, the same as a sequence save, and a member.

arm_key: the version to keep, arms[].key from experiments-get with format json (a, b, ...).
Check canMakeDefault there first. Refused (400) below proven without a guardrail breach,
and for a version a guardrail fired on. invalid_state when the kept version is paused or
deleted or nothing else is active; conflict when a default is already open or the
sequence was saved meanwhile (read again, then retry).

Turns the other active versions off through the normal sequence save and records exactly
which (deactivatedStepIds), so experiments-undo-default turns those back on. Returns the default
{id, experimentId, campaignId, sequenceId, stepOrder, keptStepId, deactivatedStepIds,
source, madeBy, madeAt}.

experiments-undo-default

Write. Early access: needs experiments on for the workspace. DELETE https://api.ken.so/v1/experiments/{experimentId}/default

Path: experimentId

Undo a finding's default: turn back on exactly the versions experiments-make-default turned off. Needs confirm=true.

DELETE /api/v1/experiments/{experimentId}/default. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Needs Campaigns edit, the same as a sequence save, and a member. A version deleted
since stays gone; one turned on by hand meanwhile is left on. invalid_state when the
finding has no open default. Returns the default with undoneBy, undoneAt and
reactivatedStepIds.

experiments-unwatch

Write. Early access: needs experiments on for the workspace. DELETE https://api.ken.so/v1/experiments/{experimentId}/watch

Path: experimentId

Stop watching a finding. Idempotent.

DELETE /api/v1/experiments/{experimentId}/watch. Sends Ken-Version 1.1 and X-Ken-Actor:
agent. Needs Campaigns edit and a member. Returns {"success": true} (the API answers 204).

experiments-update

Write. Early access: needs experiments on for the workspace. PATCH https://api.ken.so/v1/experiments/{experimentId}

Path: experimentId

Body (json): bucket string, customName string, isDismissed boolean

Rename, dismiss or move a finding. Dismissed findings come back when their proof level changes.

PATCH /api/v1/experiments/{experimentId}. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Needs Campaigns edit and a member (a key without one is 403).

custom_name: the member's name, at most 256 characters. clear_custom_name=true brings
Ken's name back. dismissed=true dismisses at the current proof level (records who, when
and the proof); dismissed=false makes it active again. bucket (working, not_working,
too_early) moves the card there for the member and records who and when; the nightly run
never undoes it, and Ken's own read stays in detectedBucket. Moving it to Ken's read, or
reset_bucket=true, clears the move. Give bucket or reset_bucket, not both. A move sends,
pauses and edits nothing. Give at least one. An archived finding cannot be dismissed or
moved (invalid_state), only reset. Returns the finding.

experiments-watch

Write. Early access: needs experiments on for the workspace. PUT https://api.ken.so/v1/experiments/{experimentId}/watch

Path: experimentId

Watch a finding for the caller's own member. Idempotent.

PUT /api/v1/experiments/{experimentId}/watch. Sends Ken-Version 1.1 and X-Ken-Actor: agent.
Needs Campaigns edit and a member (a key without one is 403). Returns data {experimentId,
isWatching}.