Kenso MCP tools

Triggers triggers

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through triggers_read and changes through triggers_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: signals-create, triggers-create, delete, funding-rounds-export, funding-rounds-get, sending-capacity-get, trigger-capacity-get, triggers-get, get-stats, trigger-firings-list, trigger-schemas-list, triggers-list, funding-rounds-search, trigger-capacity-update, triggers-update, campaign_get, campaign_set, client

signals-create

Write. POST https://api.ken.so/v1/signals

Body (json): isSynthetic boolean, signals array

Queue signals for the current workspace. type and source are lowercase snake_case. Requires Search edit access (owners, admins and editors by default).

POST /api/v1/signals. Public. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
The workspace header is the only client_id written. Omit is_synthetic for true.
Non-super-admins stay synthetic. Returns acceptedCount, duplicateCount (dedupKey
already queued in the last 24 hours) and isSynthetic. signals holds 1 to 1000
items for super admins and 1 to 100 for everyone else, and each one counts
against the workspace's signal quota (429 when spent). payload is a JSON object
of at most 16 KB; dedupKey is at most 200 characters. A contact, campaign, or
segment outside the workspace is rejected before publish.

triggers-create

Write. POST https://api.ken.so/v1/triggers

Body (json): audienceFilter string, campaignId integer, cooldownMinutes integer, maxAgeMinutes integer, parameters string, priority integer, signalType string, stopSourceSequence boolean, switchCampaignToTrigger boolean, tier string

Create a trigger definition on a campaign. Public. Requires Campaigns edit access (owners, admins and editors by default). Omitted timing fields use the API defaults.

POST /api/v1/triggers. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Returns 201. signal_type and tier are lowercase snake_case.
Leave tier out: it is deprecated and has no effect (DEV-7900). Every trigger is processed at
the same speed whatever its tier; max_age_minutes bounds how long a firing may wait.
parameters is a JSON object or a JSON object string. The campaign must belong to the workspace.
audience_filter limits the trigger to contacts from source campaigns, the same way:
'{"sourceCampaignIds": [12, 34]}'. Omit it to match every campaign (job_change requires it).

fundraising ("Raised funding", SignalType 11) takes camelCase keys, all optional, and
"{}" is valid. Example: parameters='{"raisedWithinDays": 30, "minRaisedUsd": 2000000,
"industryGroups": ["Computers"], "states": ["CA"], "titles": ["CEO"],
"maxContactsPerCompany": 5}'.
- Round filters: raisedWithinDays 1-365 (default 30), minRaisedUsd and maxRaisedUsd
  (new money raised in the round, whole USD, >= 0, min <= max), newRoundsOnly
  (default false, skips updates to an earlier round), industryGroups,
  excludeIndustryGroups, states (2-letter codes), revenueRanges,
  incorporatedWithinYears 1-100.
- People: includeNamedExecutives (default true, the executives named on the round),
  titles, excludeTitles, seniorityLevels, functions, countries, maxContactsPerCompany
  1-50 (default 5).
Unknown keys are rejected, including the retired raisedFundingWithinDays. Try the
round filters with the funding-rounds-search operation first. Its keys differ:
reportedWithinDays, amountRaisedUsd {min, max}, industries {include, exclude},
location {states}, and foundedWithinYears. trigger-schemas-list returns the same
fields and defaults.

open_roles ("Open roles", SignalType 18) fires for contacts at companies with open public job
posts matching the job filter. jobTitles is required; the rest is optional. Example:
parameters='{"jobTitles": ["sales development representative"], "locations": ["United States"],
"minOpenJobs": 2, "maxContactsPerCompany": 3}'. The keys are camelCase.
- Job filter: jobTitles 1-50 phrases of 2+ characters, locations, sources (a known job board
  key such as greenhouse or lever), minOpenJobs >= 1 (default 1).
- Company size: minCompanySize and maxCompanySize (>= 1, min <= max), the company's current
  headcount in Kenso Search. Both existing contacts and sourced people fire only at companies in
  that range; a company with no known headcount never passes a size limit.
- People: titles, excludeTitles, seniorityLevels, functions, countries, maxContactsPerCompany
  1-50 (default 5).
Every list takes up to 50 items. trigger-schemas-list returns the fields and defaults.

Every signal type refuses a parameters key it does not take (400 naming the key and the keys
it takes), instead of dropping it.

The campaign is trigger-mode for every type except the two LinkedIn warm signals, which
import people into a regular campaign and need the workspace's linkedin_signals flag (else
400 on signalType). switch_campaign_to_trigger=true accepts a Batch campaign and switches it
to Trigger mode in the same transaction as the create, so a failed create leaves it in Batch
(default false; a LinkedIn signal never switches; Trigger back to Batch stays refused).

linkedin_post_engagement parameters (camelCase, all optional, "{}" is valid):
  linkedinAccountIds   [int]  seats whose own posts are read (max 50; empty: every connected seat)
  companyPageUrls      [str]  LinkedIn company pages whose posts are read (max 3)
  postUrls             [str]  pasted post links, any author (max 10 active per workspace; a post older than 30 days is refused)
  postReaderLinkedinAccountId  int  the seat that reads pasted posts; default: the connected seat with the most read budget left
  kinds                [str]  any of reaction, comment, reply, and author with topics (default reaction, comment, reply;
                              with topics or watchedProfileUrls: comment, reply, plus author with topics)
  reactionTypes        [str]  any of like, celebrate, support, love, insightful, funny (default any)
  commentKeywords      [str]  a comment or reply must match one (whole words, plurals and one typo tolerated; max 20)
  intents              [str]  any of positive, requesting, question, neutral, negative (default any; reactions have no intent;
                              with topics or watchedProfileUrls and intents left out: positive, requesting, question)
  postMaxAgeDays       int    1-30, default 14
  maxNewLeadsPerDay    int    1-500, default 100
  topics               [str]  keywords or phrases whose new posts are found and read (max 5, 100 characters each)
  watchedProfileUrls   [str]  LinkedIn profile or company page URLs whose new posts are found and read (max 10)
  headlineKeywords     [str]  with topics or watchedProfileUrls only: a person with a headline must match one (max 20)
  headlineExcludeKeywords [str]  with topics or watchedProfileUrls only: a headline matching one is left out (max 20)
A trigger with topics or watchedProfileUrls (listening) lists no linkedinAccountIds, companyPageUrls,
postUrls or postReaderLinkedinAccountId, and needs the linkedin_topic_signals flag on top of
linkedin_signals (else 400). author is the person who wrote a post a topic found. A workspace listens
to at most 10 topics and 20 watched URLs across its triggers (else 400). Posts are read 24 to 72 hours
after they are published, through a LinkedIn account with research reads on; with none, the trigger
returns listeningIdleReason no_opted_in_seat.
linkedin_profile_view takes linkedinAccountIds (Premium seats only; empty means every connected
Premium seat) and maxNewLeadsPerDay. A daily sweep imports new engagers into the campaign;
triggers-list-linkedin-engagements shows what it stored.

delete

Write. DELETE https://api.ken.so/v1/triggers/{triggerId}

Path: triggerId

Archive a trigger definition. Public. Requires Campaigns edit access (owners, admins and editors by default). Returns 204.

DELETE /api/v1/triggers/{triggerId}. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.

funding-rounds-export

Write. POST https://api.ken.so/v1/funding-rounds/search/export

Export funding rounds as JSON or CSV. Metered, so browse with search first. Public. Use search for browsing and export only when the user wants the rows as a file. body takes the search filters plus format (json or csv) and limit.

POST /api/v1/funding-rounds/search/export. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id.

Use search for browsing, which is free. Export only when the user wants the rounds
as a file or needs every match in full.

Metered. The allowance is set by the plan and is 5,000 rows per calendar month (UTC)
per workspace by default. One export returns at most 5,000 rows, and each returned
row uses one row of the allowance.

body takes the same filters as search. It has no cursor, groupBy, or includeFacets.
Extra fields:
- format: "json" (default) or "csv".
- limit: 1-5000, default 100. limit is a cap on matches, not a page size. The export
  runs only when every matching round fits: if more rounds match than the effective
  limit (the smaller of limit, 5000, and the rows left this month), the call fails
  with export_limit_exceeded, returns nothing, and uses no allowance. Run search
  with totalMode "exact" first, narrow the filters to what the user needs, then set
  limit to that total. Do not set 5000 by default.

Exports are not idempotent. Each successful call is charged. After a client-side
timeout or network error the export may still finish and charge, so tell the user
rather than retrying in a loop.

Returns: format "json" returns data {fundingRounds: [fundingRound], total}. format
"csv" returns {format: "csv", rowCount, csv}, where csv is the file text and
rowCount is the number of rows. The CSV header is funding_round_id, reported_at,
first_sale_at, is_new_round, amount_raised_usd, round_raised_usd, round_size_usd,
investor_count, industry, revenue_range, company_name, company_domain,
company_website, company_linkedin, company_city, company_state,
company_founded_year, executives. executives is the executive officers' names,
joined with "; ".

Errors. No allowance left this month is a plan refusal with code
FUNDING_EXPORT_ROWS_LIMIT_REACHED, metric funding_export_rows, and the used, limit,
and remaining counts. It resets on the first of the next month. Use search
meanwhile. A match set above the limit is export_limit_exceeded with count and
limit: narrow the filters until at most limit rounds match. A malformed filter is
validation_failed and names the field. A query that ran too long (503 with detail
code query_timeout, or 504 upstream_timeout): retry once with narrower filters or a
smaller limit. A busy data store or allowance store (503 with detail code
unavailable, or the message "The export allowance is unavailable."): retry once in
a minute. Any other 503 service_unavailable means funding rounds are off or the
data is down: tell the user and do not retry in a loop. None of these use allowance.

Example: operation="funding-rounds-export", body={"reportedWithinDays": 7,
"amountRaisedUsd": {"min": 5000000}, "format": "csv", "limit": 200}, client_id=123

funding-rounds-get

Read. GET https://api.ken.so/v1/funding-rounds/{fundingRoundId}

Path: fundingRoundId

Get one funding round with its company, people, and the round's other reports. Public and free. funding_round_id is the id from search, such as fr_000123456726000123.

GET /api/v1/funding-rounds/{fundingRoundId}. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Does not use the export allowance.

funding_round_id is fr_ followed by 18 digits. Returns data: the fundingRound (the
same shape as in search, with company and people) plus history, the round's other
reports, oldest first. Each history item has id, reportedAt, isNewRound,
amountRaisedUsd, and roundRaisedUsd. A missing id is not_found.

Example: operation="funding-rounds-get", funding_round_id="fr_000123456726000123",
client_id=123

sending-capacity-get

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

Read remaining daily send capacity for checkout and domain import. Internal. Requires Delivery view.

GET /api/v1/sending-capacity. Internal. Sends Ken-Version 1.1.
Returns emailLimit, planDaily, existingCapacity, remaining, and provider counts.
planDailyEnforced (DEV-1544 B06) says whether planDaily is a hard cap: true
for Premium (VIP), false for credit plans and bypass workspaces (planDaily
is then a planning figure and each Kenso inbox costs 200 credits a month).
Missing before B06: treat it as true.

trigger-capacity-get

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/trigger-capacity

Path: campaignId

Read one campaign's trigger capacity. Internal. A campaign outside the workspace is not_found.

GET /api/v1/campaigns/{campaignId}/trigger-capacity.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires Campaigns view.
The client send-budget read stays on GET /v1/triggers/capacity.

triggers-get

Read. GET https://api.ken.so/v1/triggers/{triggerId}

Path: triggerId

Get one trigger definition. Public. A trigger outside the workspace is not_found.

GET /api/v1/triggers/{triggerId}. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires Campaigns view. listeningIdleReason no_opted_in_seat: the trigger lists topics or
watchedProfileUrls and no LinkedIn account has research reads on (absent otherwise).

get-stats

Read. GET https://api.ken.so/v1/triggers/{triggerId}/stats

Path: triggerId

Query: days integer

Firing stats for one trigger. Public. days is 1 to 90. Omit it to use the API default of 7.

GET /api/v1/triggers/{triggerId}/stats. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires Campaigns view.

trigger-firings-list

Read. GET https://api.ken.so/v1/trigger-firings

Query: cursor string, limit integer, status string, triggerId integer

List trigger firings in the current workspace. Public. status is pending, processing, exported, suppressed, or failed.

GET /api/v1/trigger-firings. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires Campaigns view. This route is not nested under /v1/triggers.

trigger-schemas-list

Read. GET https://api.ken.so/v1/trigger-schemas

List parameter schemas for each signal type. Public. Signal names in the response are lowercase snake_case.

GET /api/v1/trigger-schemas. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires Campaigns view.

triggers-list

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

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

List trigger definitions in the current workspace. Public. status is active, paused, or archived.

GET /api/v1/triggers. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires Campaigns view. status is lowercase snake_case. limit is 1 to 200.
listeningIdleReason: see triggers-get.

Read. POST https://api.ken.so/v1/funding-rounds/search

Search funding rounds: companies that just raised money, with the amounts. Public and free. body is the filter object, and an empty object returns the newest rounds. Browse here, export later.

POST /api/v1/funding-rounds/search. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Does not use the export allowance.

A funding round is one report of a company raising money: the amount raised, the
round's running total and target size, the investor count, and the executives and
directors named on it. The data is global, not per workspace. Use it to find
companies that raised recently and to read a round. The same filters drive the
Fundraising trigger (SignalType 11).

body is the request object. Every filter is optional and an unknown key is
validation_failed. Filters:
- companies {include: [domains or names], exclude: [...]}.
- companyIds: company ids (company.id) from earlier results.
- companyKinds: operating_company (default), investment_fund, real_estate,
  financial_services, other, or "all". The default hides funds, real estate
  projects, and banks, so a plain search returns operating companies.
- industries {include: [...], exclude: [...]}. Values: Agriculture, Commercial
  Banking, Insurance, Investing, Investment Banking, Pooled Investment Fund, Other
  Banking and Financial Services, Business Services, Coal Mining, Electric Utilities,
  Energy Conservation, Environmental Services, Oil and Gas, Other Energy,
  Biotechnology, Health Insurance, Hospitals and Physicians, Pharmaceuticals, Other
  Health Care, Manufacturing, Commercial, Construction, REITS and Finance,
  Residential, Other Real Estate, Retailing, Restaurants, Computers,
  Telecommunications, Other Technology, Airlines and Airports, Lodging and
  Conventions, Tourism and Travel Services, Other Travel, Other. Software companies
  are under Computers or Other Technology.
- location {states: ["CA"], cities: ["San Francisco"]}. States are 2-letter codes.
- amountRaisedUsd, roundRaisedUsd, roundSizeUsd: {min, max} in whole USD.
  amountRaisedUsd is the new money in this report, not the running total.
  roundRaisedUsd is the round's running total. roundSizeUsd is the round's target
  size, which an open-ended round does not have.
- reportedAfter, reportedBefore: yyyy-MM-dd. reportedWithinDays: days, 1-36500.
- newRoundsOnly: only the first report of each round, not its later updates.
- revenueRanges: "No Revenues", "$1 - $1,000,000", "$1,000,001 - $5,000,000",
  "$5,000,001 - $25,000,000", "$25,000,001 - $100,000,000", "Over $100,000,000",
  "Decline to Disclose", "Not Applicable".
- hasDomain: true for companies with a website.
- foundedWithinYears: 1-200.

Options: limit 1-50 (default 25). cursor: pass pagination.nextCursor from the
previous page with the same filters. totalMode: "none", "capped" (default, counts
to 1,000), or "exact". includeFacets adds counts by industries, states,
amountBuckets, and companyKinds. groupBy: "company" returns one row per company
instead of one per round, with a different shape (below).

Returns data {fundingRounds: [fundingRound], total, totalIsCapped, pagination:
{nextCursor}, facets}. totalIsCapped is true when total stopped at the cap. A
fundingRound has id (fr_ and 18 digits, pass it as funding_round_id to get),
reportedAt, firstSaleAt, isNewRound, amountRaisedUsd, roundRaisedUsd, roundSizeUsd
(null when isOpenEnded), isOpenEnded, remainingUsd, minimumInvestmentUsd,
investorCount, industry, revenueRange, company {id, name, domain, websiteUrl,
linkedinUrl, city, state, foundedYear, kind}, and people [{name, roles}]. roles are
executive_officer, director, and promoter. Amounts can be null: show a dash, not $0.

With groupBy "company", data has companies and no fundingRounds key: data {companies:
[{company, roundCount, newestReportedAt, totalRaisedUsd, newestRound, executives}],
total, totalIsCapped, pagination: {nextCursor}, facets}. total counts companies.
roundCount is how many of the company's rounds match. newestRound is its newest
matching fundingRound. executives are the executive officers named on that round,
each with name and roles.

Errors: 400 validation_failed names the bad field. A query that ran too long (503
with detail code query_timeout, or 504 upstream_timeout): retry once with narrower
filters. A busy data store (503 with detail code unavailable): retry once in a
minute. Any other 503 service_unavailable means funding rounds are off or the data
is down: tell the user and do not retry in a loop.

Example: operation="funding-rounds-search", body={"reportedWithinDays": 14,
"amountRaisedUsd": {"min": 2000000}, "industries": {"include": ["Computers"]},
"location": {"states": ["CA"]}, "limit": 25}, client_id=123

trigger-capacity-update

Write. PUT https://api.ken.so/v1/campaigns/{campaignId}/trigger-capacity

Path: campaignId

Body (json): dailyCap integer

Set or clear one campaign's daily trigger cap. Internal. Requires full access. daily_cap null clears the cap.

PUT /api/v1/campaigns/{campaignId}/trigger-capacity.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id. This update stays PUT.

triggers-update

Write. PATCH https://api.ken.so/v1/triggers/{triggerId}

Path: triggerId

Update a trigger definition. Omitted fields stay unchanged. signalType and campaignId cannot be changed. audienceFilter null clears the filter.

PATCH /api/v1/triggers/{triggerId}. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Requires Campaigns edit access (owners, admins and editors by default). tier and status are lowercase snake_case.
tier is deprecated and has no effect (DEV-7900): every trigger is processed at the same speed.
parameters and audienceFilter take a JSON object or a JSON object string.

campaign_get

Read.

Client trigger capacity and per-campaign daily caps. Ops: client (default), campaign_get, campaign_set.

View a client's send-capacity budget and manage per-campaign trigger daily caps.

### operation=client (default)
Returns the last `days` client_send_budget rows (newest last). Each row is an
advisory daily plan, not a limit: batch campaigns are not capped by it, and
triggers take precedence over batch sends on shared inboxes at dispatch.
Fields: capacitySnapshot (healthy-inbox daily capacity), headroomTarget,
triggerForecast, triggerAllowance and batchCapSet (the planned split),
triggerAdmitted and batchDisplaced (legacy counters, no longer written), and
fleetRecommendation (weekly trend JSON; do not act on it: its trigger-volume
input is the legacy triggerAdmitted counter, which nothing writes, so any
value is not based on real send volume. The job now skips clients whose
whole series is zero, and the field is usually null).

### operation=campaign_get
Requires campaign_id. Returns the per-campaign trigger daily cap
(GET /v1/triggers/capacity/campaigns/{campaignId}).

### operation=campaign_set
Requires campaign_id and either daily_cap (>= 1) or clear_daily_cap=True
(sends dailyCap=null to remove the cap). Only valid for Trigger-mode
campaigns - Batch campaigns return a validation error.

Use to answer: "how much daily inbox capacity does this client have?", "should
this client add or remove inboxes?", "cap this trigger campaign at N sends/day".
For per-definition firing stats use triggers(operation='get-stats').

campaign_set

Write.

Client trigger capacity and per-campaign daily caps. Ops: client (default), campaign_get, campaign_set.

View a client's send-capacity budget and manage per-campaign trigger daily caps.

### operation=client (default)
Returns the last `days` client_send_budget rows (newest last). Each row is an
advisory daily plan, not a limit: batch campaigns are not capped by it, and
triggers take precedence over batch sends on shared inboxes at dispatch.
Fields: capacitySnapshot (healthy-inbox daily capacity), headroomTarget,
triggerForecast, triggerAllowance and batchCapSet (the planned split),
triggerAdmitted and batchDisplaced (legacy counters, no longer written), and
fleetRecommendation (weekly trend JSON; do not act on it: its trigger-volume
input is the legacy triggerAdmitted counter, which nothing writes, so any
value is not based on real send volume. The job now skips clients whose
whole series is zero, and the field is usually null).

### operation=campaign_get
Requires campaign_id. Returns the per-campaign trigger daily cap
(GET /v1/triggers/capacity/campaigns/{campaignId}).

### operation=campaign_set
Requires campaign_id and either daily_cap (>= 1) or clear_daily_cap=True
(sends dailyCap=null to remove the cap). Only valid for Trigger-mode
campaigns - Batch campaigns return a validation error.

Use to answer: "how much daily inbox capacity does this client have?", "should
this client add or remove inboxes?", "cap this trigger campaign at N sends/day".
For per-definition firing stats use triggers(operation='get-stats').

client

Read.

Client trigger capacity and per-campaign daily caps. Ops: client (default), campaign_get, campaign_set.

View a client's send-capacity budget and manage per-campaign trigger daily caps.

### operation=client (default)
Returns the last `days` client_send_budget rows (newest last). Each row is an
advisory daily plan, not a limit: batch campaigns are not capped by it, and
triggers take precedence over batch sends on shared inboxes at dispatch.
Fields: capacitySnapshot (healthy-inbox daily capacity), headroomTarget,
triggerForecast, triggerAllowance and batchCapSet (the planned split),
triggerAdmitted and batchDisplaced (legacy counters, no longer written), and
fleetRecommendation (weekly trend JSON; do not act on it: its trigger-volume
input is the legacy triggerAdmitted counter, which nothing writes, so any
value is not based on real send volume. The job now skips clients whose
whole series is zero, and the field is usually null).

### operation=campaign_get
Requires campaign_id. Returns the per-campaign trigger daily cap
(GET /v1/triggers/capacity/campaigns/{campaignId}).

### operation=campaign_set
Requires campaign_id and either daily_cap (>= 1) or clear_daily_cap=True
(sends dailyCap=null to remove the cap). Only valid for Trigger-mode
campaigns - Batch campaigns return a validation error.

Use to answer: "how much daily inbox capacity does this client have?", "should
this client add or remove inboxes?", "cap this trigger campaign at N sends/day".
For per-definition firing stats use triggers(operation='get-stats').