Kenso MCP tools

Analytics Campaign analytics_campaign

Not for one campaign's event counts between two dates: that is analytics(operation="get-counts", campaign_id, from_time, to_time). query: metric series and breakdowns, metrics from contacted, sent, delivered, bounced, clicked, replies, interested, meetings, invites, accepted and their rates; group_by up to 2 of campaign, segment, step, variant, channel, inbox, day, week, ...; filters {campaignId: [id], channel: ["linkedin"], ...}; window {preset: last_7_days} or {from, to}. It has no campaign_id or date fields; a daily series to chart is group_by day. dashboard is the workspace view (view summary, chart or campaigns). sending-capacity-get-forecast: the sending forecast of every campaign.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through analytics_campaign_read. 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: sending-capacity-get-forecast, get-mail-providers, get-variant-performance, list-recipient-providers, query, experiments-significance, experiments-warm-paths, dashboard

sending-capacity-get-forecast

Read. GET https://api.ken.so/v1/sending-capacity/forecast

Forecast the workspace's email sends: capacity, planned and remaining per day. Public. Delivery view. Covers UTC today and the next two days.

GET /api/v1/sending-capacity/forecast. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id; reads only the caller's own workspace (DEV-5222).
Returns calculatedAt and days, three rows for UTC today, tomorrow and the
day after. Each row has date (YYYY-MM-DD), capacity (emails the
workspace's healthy inboxes can send in a day), planned (emails already
queued or planned for that day) and remaining (capacity minus sent and
planned, never below 0). Today's row also has sent (emails already sent
since UTC midnight); later rows leave it out. The planner plans about 36
hours ahead, so planned for
the later days fills in as it reaches them. Capacity is the same each day
and does not skip a campaign's non-sending days.
Takes no what-if inputs: staff use admin_sequencer_plan
operation get-capacity-forecast for those. For one campaign's expected
volume use campaign_flow operation get-launch-readiness.

get-mail-providers

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/mail-providers

Path: campaignId

Count one campaign's contacts by email security gateway (Proofpoint, Mimecast, ...) and by mailbox host. Read-only, no credits. Needs security gateways on the workspace. A cross-workspace id is not_found.

GET /api/v1/campaigns/{campaignId}/mail-providers. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Requires Campaigns view. Without the security
gateways feature on the workspace the campaign is not_found (404).

Each live contact counts once, judged by its first Safe or Verified email (the
securityGateway and mailboxProvider of contacts(operation="search") and the lead
list columns read the same email).

Returns data {gateways, mailboxProviders, pendingCount, isPartial}.
gateways is every active gateway in the catalog, 0 included, most contacts first:
{slug, name, count}. mailboxProviders is the same for mailbox hosts and forwarders
(google_workspace, microsoft_365, ...). Contacts with no gateway, an unknown host or
no deliverable email are in neither list. pendingCount is the contacts whose domain
is not checked yet (gateway status pending). isPartial is true when the campaign has
more than 100,000 live contacts: the counts cover the first 100,000 by id.
Pass a slug to contacts(operation="search") security_gateway or mailbox_provider to
list those contacts.

get-variant-performance

Read. Early access: needs variant_performance on for the workspace. GET https://api.ken.so/v1/analytics/variant-performance

Query: campaignId integer, from date, timeZone string, to date

Split one campaign's contacted, replies and interested replies by step and variant. Shows which variant of each step wins. Rates are over contacted.

GET /api/v1/analytics/variant-performance. Sends Ken-Version 1.1. client_id is sent
as X-Ken-Workspace-Id. Needs the workspace's variant_performance flag (the route is
404 and the operation hidden while it is off) and Campaigns view, so with the flag on
a client seat reads its own workspace's campaigns. A campaign outside the workspace is
not_found.
Each call counts on the workspace's analytics query quota (60 a minute, 3,000 a day).

campaign_id is required. from_date and to_date are inclusive calendar days
(YYYY-MM-DD) in time_zone (an IANA id; default the campaign's sending zone, else UTC),
at most 400 days; leave both out for the campaign to date.

Counting: distinct contacts per row. contacted is the people sent that step and
variant, replies the people who replied (out-of-office and other non-replies do not
count), interested the people with an interested reply. Each reply counts against the
step and variant of the send it answers, whenever it arrived (the cohort basis), so
reply_rate and positive_reply_rate are over contacted and stay 0 to 1, null when nobody
was contacted.

Response: window {from, to, timeZone}, rows, totals, truncated and asOf. Each row has
dimensions {step, variant}, labels {step: "Step 2", variant: "Variant B"}, metrics
{contacted, replies, interested, reply_rate, positive_reply_rate}, sample and
stillFilling: true while most of the row's sends are under 7 days old, so replies to
them are still arriving and the row is too early to call.
LinkedIn rows are labelled "LinkedIn step N" and "LinkedIn variant X". A contact with
no variant is the Unknown row (variant null). To test whether one variant really
beats another, use analytics_campaign(operation="experiments-significance",
campaign_id=42, step=2) where the workspace has experiments on.

list-recipient-providers

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/recipient-providers

Path: campaignId

Count a campaign's leads by mailbox provider and security gateway. Requires Campaigns view.

GET /api/v1/campaigns/{campaignId}/recipient-providers. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Needs the sender_routing flag.
Every active mailbox provider and security gateway (slug, name, kind, leadCount),
0 included, most leads first. A lead counts under its mailbox provider and its
gateway. pendingCount: provider still being detected. noProviderCount: no listed
provider. isPartial: counts cover the first 100,000 leads.

query

Read. Early access: needs generative_ui on for the workspace. POST https://api.ken.so/v1/analytics/query

Body (json): compareTo string, filters object, groupBy array, limit integer, metrics array, rateBasis string, timeZone string, window object

Query workspace outreach metrics, grouped by up to 2 dimensions, over a window. Email and LinkedIn counts and rates (event-time or cohort) with optional previous-period comparison.

POST /api/v1/analytics/query. Sends Ken-Version 1.1. client_id is sent as
X-Ken-Workspace-Id. Staff exposure, opened per workspace by the generative_ui flag.
The body is metrics, group_by, filters, window, compare_to, time_zone, limit and
rate_basis. This tool checks only what the backend always rejects: 1 to 8 metrics, at
most 2 group_by names, compare_to previous_period, limit 1 to 200 (API default 50),
rate_basis event_time or cohort, and the time zone. Metric and dimension names, filter
shapes and the window are checked by the backend and its validation_failed details
(one per field) come back as is.

metrics (1 to 8, no repeats): contacted, sent, delivered, bounced, clicked, replies,
interested, not_interested, unsubscribed, meetings, invites, accepted, reply_rate,
positive_reply_rate, bounce_rate, acceptance_rate. reply_rate and positive_reply_rate
are over contacted, bounce_rate is bounced over email sends, acceptance_rate is
accepted over invites. invites, accepted and acceptance_rate are LinkedIn only.
Rates are event-time ratios: numerator and denominator are counted by event time in
the same window and group, so a rate is usually 0 to 1 but can exceed 1 in short
windows, day or week buckets or by step when replies or accepts answer earlier sends
(a verdict on such counts is too_early). A rate is null when the denominator is zero.

rate_basis (default "event_time", which matches the Kenso dashboard): "cohort" counts each
reply and accept against the send it answers (the contact's latest email in the
campaign, or the latest LinkedIn send or invite, at or before it), in that send's step,
variant, inbox, segment and day, whenever it arrived. replies, interested,
not_interested, accepted and their rates then stay within each row's contacted and
invites (0 to 1). Every other metric is event-time on both bases. Use cohort to compare
steps, variants or days; use the default for totals that must match the dashboard.
With cohort, each row and the totals carry stillFilling: true while most of their sends
are under 7 days old, so replies are still arriving and a low rate is not yet a verdict.

group_by (at most 2): campaign, segment, step, variant, channel, inbox, domain,
seniority, function, title_group, industry, company_size, country, week, day, language.
All null values share one Unknown row, labelled "Unknown". LinkedIn rows are Unknown by
inbox and domain. Step and variant labels read "LinkedIn step N" and
"LinkedIn variant X" for LinkedIn rows. Meetings carry no channel: a channel filter
leaves them out, and grouped by channel they are the Unknown row.
language is the language an email went out in (fr-FR, en, ...); a reply takes the
language of the send it answers. Only email sends and replies carry one: every other
event, and a send before 2026-10-29, is the value unknown, labelled "Not recorded".

filters: an object of non-empty arrays. Keys are campaignId, segmentId, inboxId,
domainId (ids), step (step numbers), channel (email or linkedin), variant,
seniority, function, title_group, industry, company_size, country and language (strings).
Week and day only split, the window filters time. channel is email or linkedin,
and no channel filter counts both.

window (required): {"preset": "last_7_days" | "last_14_days" | "last_30_days" |
"last_90_days" | "campaign_to_date"} or {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}
(inclusive calendar days in time_zone, at most 400 days), never both.
campaign_to_date needs exactly one campaignId filter. time_zone is an IANA id such
as Europe/Bucharest.

compare_to "previous_period" fills each row's and the totals' previous values and the
response's previousWindow. Without it previous and previousWindow are null. Rows
grouped by day or week get previous null (the previous window holds other dates; only
a week straddling both windows matches its earlier days), so compare the totals.

Response: window, previousWindow, rows, totals, truncated and asOf. Each row has
dimensions (wire names), labels, metrics (the requested ones only), previous and
sample (the counts behind the rates). When bounce_rate is requested, sample carries
email_sent, the email sends it is over. truncated is true when limit cut the rows.
stillFilling is on rows and totals only with rate_basis cohort.

experiments-significance

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

Query: campaignId integer, controlContactedCount integer, controlInterestedCount integer, from date, step integer, timeZone string, to date, variantContactedCount integer, variantInterestedCount integer

Test whether one arm beats another with the Experiments math: proof proven, leaning or cant_tell, and an interval. Two arms of counts, or a campaign step's email variants. Run it before calling any arm a winner.

GET /api/v1/experiments/significance. Sends Ken-Version 1.1. client_id is sent as
X-Ken-Workspace-Id. Needs Campaigns view (a client seat included) and the workspace's
experiments flag. Nothing is stored. Needs no ken-website token, unlike
free_tools(operation="calculate"). A campaign step counts one unit on the workspace's
analytics query quota (60 a minute, 3,000 a day); two arms of counts count nothing.

Send exactly one of:
- control_contacted, control_interested, variant_contacted, variant_interested: the people
  each arm reached and how many of them replied interested (interested at most contacted).
  The arms are labelled control and variant.
- campaign_id and step: that step's email variants, counted like
  analytics_campaign(operation="get-variant-performance", campaign_id=42) over from_date to
  to_date (inclusive YYYY-MM-DD days in time_zone; leave both out for the campaign to
  date). Variant A is the control; every other variant is compared with it.

Ken grades the arms the way the Experiments page grades a version test, read once today:
a single look at the sequential boundary for the information the counts give, with no
day-by-day history, so it cannot see a boundary crossed on an earlier day. The counts are
taken as given (no sample-ratio check, no reply audit) and are not matured 21-day cohorts,
so an experiments finding, when there is one (operation experiments-list), is the better read.

What proof means: proven is the difference is real (the boundary is crossed) and the arm
can be called a winner or a loser; leaning is more likely than not (80% or more) but not
proven, so say "leaning", never "won"; cant_tell is not enough data or no difference yet.
verdict is better, worse, about_the_same, no_difference_yet, unlikely_to_separate or
not_enough_data, about headlineArm against controlArm. estimate is the shrunk relative lift
(0.12 is +12%) and interval {low, high} its range at intervalLevel 0.8. pBetter is the
chance the headline arm is better. informationFraction is the counts over nMax, the planned
contacts per arm (sized for a +50% lift at baselineRate, from the arms when they hold 500+
contacts, else 1%); a first read needs 0.25 (reason below_first_read until then).
Response: proof, verdict, controlArm, headlineArm, estimate, interval, intervalLevel,
pBetter, zStatistic, boundary, informationFraction, nMax, baselineRate, baselineSource,
reasons, arms [{label, contactedCount, interestedCount, interestedRate,
interestedInterval}], comparisons [{arm, control, proof, verdict, estimate, interval,
pBetter, reasons}], and for a campaign step campaignId, step, from, to and timeZone.

experiments-warm-paths

Read. Early access: needs accounts, linkedin_network, warm_paths_v2 on for the workspace. GET https://api.ken.so/v1/experiments/warm-paths

Query: runId integer

Read warm path outcomes as experiments: the per-hop funnel, which message parts work, and warm vs the cold control. Counts only, never a person. Run it before saying a blurb, opener or warm paths themselves work.

GET /api/v1/experiments/warm-paths. Staff; sends Ken-Version 1.1 and X-Ken-Actor: agent.
client_id is sent as X-Ken-Workspace-Id. Needs Accounts view and the workspace's accounts,
linkedin_network and warm_paths_v2 flags. Nothing is stored.

run_id: a list run (from linkedin_connections(operation="warm-paths-run-create")), to read only its
control comparison. Another workspace's run, or with account scope own a run another member
queued, is not found.

Response:
- funnel: asksSentCount (connector asks sent), asksAgreedCount, introsMadeCount (intro
  replies sent), pointersAnsweredCount (pointer asks whose answer moved the path on),
  targetsRepliedCount (paths whose target answered), and actions [{hopAction, sentCount,
  repliedCount, decidedCount, succeededCount, agreedCount, declinedCount, redirectedCount,
  unknownPersonCount, pointedCount, noReplyCount}]. Success is the warm path calibration
  table: agreed (connector_ask, handoff); pointed, redirected or agreed (pointer_ask); any
  reply, a decline included (direct, cold, intro_reply, referral).
- findings: one per message part (opener, hook, why_you, ask, blurb, easy_out) of a hop
  action that went out in two variants or more, or with and without it, compared on the
  hop's success: key, hopAction, part, name, proof, bucket, verdict, controlArm,
  headlineArm, estimate, interval, pBetter, reasons, claimText, progress {targetCount,
  currentCount}, arms [{key, label, variantId, sentCount, decidedCount, succeededCount,
  successRate}]. The variants went to different people at different times, so proof is
  hunch at most: say "looks ahead", never "won". cant_tell (bucket too_early) until 10 hops
  succeeded across the arms. Working first.
- control: runs (the newest 50 with a control, newest first) and workspace (those runs
  added up, each target once; omitted with run_id), each with warm and control
  {targetCount, repliedCount, replyRate, maturingCount}, proof, verdict, estimate,
  interval, pBetter, reasons and claimText. One run's split is random, so it reads
  proven, leaning or cant_tell; workspace reads hunch or cant_tell, since the runs have
  their own lists and control shares. A target counts 30 days after it was assigned,
  reached or not, and replied when it answered inside those days; until then it is in
  maturingCount. Replies only: whether a reply was interested is not read yet.
Quote claimText as given; it follows the Experiments wording rules.

dashboard

Read.

Date-windowed workspace dashboard. view=summary/chart take period or start_date/end_date. Not per-campaign totals (analytics get-campaign-performance, campaign_ops status).

Date-windowed workspace dashboard. Discriminator: ``view``.

Use view=summary or view=chart for "last week", "this month", or any
date range (period / start_date / end_date). Do not use
campaign_ops(operation="status") for those questions - it returns
lifetime campaign totals with no date window. One campaign's numbers
for a window are analytics(operation="get-campaign-performance").

Other views: campaigns (sending forecast), pipeline (processing funnel),
email_delivery (inbox/domain counts, not send stats), usage (spend).

### view=campaigns

Get active campaigns with completion stats for dashboard.

Returns active campaigns with backend-calculated campaign-level sending
forecasts based on full-sequence progress and shared sending capacity.

Parameters:
-----------
client_id : int (required)
    Client ID to get campaigns for.

Returns:
--------
dict
    List of campaigns with id, name, compatibility fields and nested
    sendingForecast (status, progressPercentage, estimatedFinishAtUtc,
    confidence/reasonCodes, capacity, scheduledNext3Days queued vs
    effectiveScheduledNext3Days will-send, calculated age). Paused
    campaigns keep queued volume but report effectiveScheduledNext3Days=0.

### view=pipeline

Get the dashboard-wide pipeline health snapshot.

Returns the backend BaseResponse envelope from GET /v1/dashboard/pipeline
without additional unwrapping. The dashboard summarizes campaign processing
across the 8 pipeline stages, in order: Import, Qualification, Enrichment,
Verification, Segmentation, Personalization, Export, Sending.

Each stage includes funnel counts: total, processed, failedCount, and
stuckCount. Status values describe the stage state and include Stalled;
stalled stages include stalledSince so callers can show when progress
stopped. The top-level asOf field indicates when the snapshot was computed
so agents can reason about staleness. A details field appears only for
admin callers. Verification, Segmentation, and Qualification stages also
carry a user-facing breakdown map of distribution counts, summed per key
across the client's active campaigns (Verification: email validity
buckets; Segmentation: contacts per segment name; Qualification:
Qualified, Unqualified, Unprocessed).

Parameters:
-----------
client_id : int (required)
    Client ID to summarize.

Response field reference:
stages: [{stage, status, total, processed, failedCount, stuckCount, lastProgressAt, stalledSince, breakdown?, details?}]
dashboard adds: stalledCampaigns: [{campaignId, name, stage, stalledSince}]

### view=email_delivery

Inbox and sending-domain counts for the dashboard card. Not send volume,
not engagement, not a date window. Returns totalInboxes (Kenso managed
inboxes from GetDashboardEmailDeliveryQuery; system mailboxes excluded),
totalDomains, inboxesPerDomain. For windowed send analytics use
view=summary or view=chart.

Parameters:
-----------
client_id : int (required)
    Client ID to get email delivery stats for.

Returns:
--------
dict
    Email infrastructure stats: totalInboxes, totalDomains, inboxesPerDomain.

### view=usage

Get billing/usage metrics for dashboard.

Returns usage metrics broken down by vendor and service category.
Defaults to current month if no dates provided.

Parameters:
-----------
client_id : int (required)
    Client ID to get usage for.
start_date : str (optional)
    Start date (YYYY-MM-DD). Defaults to first of current month. When both
    dates are given they must satisfy start_date <= end_date and span at
    most 366 days (backend cap).
end_date : str (optional)
    End date (YYYY-MM-DD). Defaults to today.

Returns:
--------
dict
    Usage data: periodStart, periodEnd, totalCostUsd, totalApiCalls, categories.
    totalCostUsd is Kenso's provider cost, not the workspace's price.
    Credits: billing operation credits-get.

### view=summary

Get aggregated analytics summary with previous period comparison for dashboard.

Returns metrics (emailsSent, contacted, clicks, replies, positiveReplies, bounces)
with value, previousValue, changePercent, and rate (where applicable).
Previous period is auto-calculated as same duration immediately before startDate.

Parameters:
-----------
client_id : int (required)
    Client ID.
period : str
    One of: 'last_7_days', 'last_30_days', 'this_month', 'custom'.
start_date : str (optional)
    Required when period='custom'. Format: YYYY-MM-DD. For 'custom' the range
    must satisfy start_date <= end_date and span at most 366 days (backend
    cap); otherwise raises KenValidationError.
end_date : str (optional)
    Required when period='custom'. Format: YYYY-MM-DD.

Returns:
--------
dict
    dateRange, previousPeriod, hasLinkedInCampaigns (true when the client has
    >=1 LinkedIn-enabled campaign), metrics (emailsSent, contacted, clicks,
    replies, positiveReplies, bounces, connectionsSent) each with
    value/previousValue/changePercent (rate is present only on the metrics
    that already carry it, e.g. replies/positiveReplies/bounces).
    connectionsSent has value/previousValue/changePercent only - no rate -
    and is the combined LinkedIn connection-request + message sends for the
    current and previous period.

### view=chart

Get time-series chart data for a single metric.

Returns daily data points (date + value) for one metric at a time.
Missing days are filled with 0. Supports cumulative mode for running totals.

Parameters:
-----------
client_id : int (required)
    Client ID.
period : str
    One of: 'last_7_days', 'last_30_days', 'this_month', 'custom'.
start_date : str (optional)
    Required when period='custom'. Format: YYYY-MM-DD. For 'custom' the range
    must satisfy start_date <= end_date and span at most 366 days (backend
    cap); otherwise raises KenValidationError.
end_date : str (optional)
    Required when period='custom'. Format: YYYY-MM-DD.
metric : str
    One of: 'emails_sent', 'contacted', 'clicks', 'replies',
    'positive_replies', 'bounces', 'connections_sent'. Default: 'emails_sent'.
    'connections_sent' (combined LinkedIn connection requests + messages sent
    per day) is meaningful only when the workspace has >=1 LinkedIn-enabled
    campaign; its per-day points additionally carry a nested
    linkedInBreakdown object with connectionsSent, messagesSent, accepted,
    skipped, failed.
cumulative : bool
    If True, returns cumulative totals. Default: False.

Returns:
--------
dict
    { metric, cumulative, data: [{ date, value }] }