Models models
AI model settings and AI runs. How many contacts a flow would touch: get-eligibility, or ai-runs-create with dry_run=true.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through models_read and changes through models_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: ai-line-holds-approve, ai-runs-create, fit-classifications-create, create, delete, ai-cost-estimate-get, ai-runs-get, get, model-training-get, get-eligibility, ai-line-holds-list, ai-lines-list, byok-models-list, list, ai-lines-regenerate, reset, ai-lines-update, update, ai_supported_models, ai_token_analysis
ai-line-holds-approve
Write. POST https://api.ken.so/v1/campaigns/{campaignId}/ai-line-holds/{contactId}/approve
Path: campaignId, contactId
Approve a held contact's lines as they are, so the contact can send them. Public. Requires Campaigns edit. Free: no AI run, not charged.
POST /api/v1/campaigns/{campaignId}/ai-line-holds/{contactId}/approve. Public.
Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. The lines the
hold keeps (models(operation="ai-line-holds-list")) become the contact's
personalization lines and the contact counts as personalized, so it can send.
Returns contactId and restoredLineCount. A contact with no hold in the campaign
(never held, already approved, or regenerated) is 409 not_held. When the contact
already has a live line for one of the held variables, or the hold keeps no lines,
it is 409 conflict and nothing changes; regenerate the contact instead
(models(operation="ai-lines-regenerate", contact_id=...)). A campaign or contact outside the
workspace, or a contact not in this campaign, is not_found. Read the held lines to
the user and ask before approving: they failed the line check once.
ai-runs-create
Write. POST https://api.ken.so/v1/campaigns/{campaignId}/ai-runs
Path: campaignId
Body (json): batchSize integer, dryRun boolean, flow string, model string, processAll boolean, provider string, segmentId integer
Queue an AI run for a campaign. Returns 202 and a GUID run id. Poll api_ai_runs_get. dry_run true previews it and queues nothing. Public. Requires Campaigns edit and the `ask` permission.
POST /api/v1/campaigns/{campaignId}/ai-runs. Public. Sends Ken-Version 1.1.
The run id is a GUID. Poll GET /api/v1/ai-runs/{aiRunId}. A campaign
outside the workspace is not_found before the run is queued.
flow is qualification, personalization, rewriting, or segmentation; any
other flow (tone_of_voice, scoring) is refused before the call. Lead scoring
is not an AI run: turn it on with campaigns(operation="replace-scoring") and
run it with campaigns(operation="run-scoring"). batch_size must be at least
1 when set. personalization and rewriting run one segment at a time, so they
need segment_id: start one run per segment (list them with
segments(operation="list")). Without it the call is refused before it is
sent, dry run included. qualification and segmentation without segment_id
run every segment. Uses credits: qualification 50 credits per 1,000 rows ($1),
personalization 300 credits per 1,000 rows ($6). Segmentation is free with
qualification. Full prices: billing operation credit-rate-card-get.
dry_run true checks the request exactly like a real run (flow, one of the
four above, batch_size, segment_id, provider, a campaign of this workspace)
and returns 200 instead of 202: data holds dryRun, campaignId, flow, segmentId,
processAll, provider, model, batchSize (the batch the run would take),
eligibleCount, projectedContactCount
(eligibleCount capped at batchSize), and blockingGate and blockingReason (set
only when a gate stops the flow). segmentId, provider, model, blockingGate and
blockingReason are left out when unset. A dry run queues nothing, reserves no
quota and spends no credits. If the answer to a dry run is not a preview
(data.dryRun true), the API queued the run for real: the result then carries
a warning saying so, and the run spends credits like any other.
fit-classifications-create
Write. Early access: needs fit_classification on for the workspace. POST https://api.ken.so/v1/fit-classifications
Body (json): estimateOnly boolean, fitDefinition string, rows array
Classify up to 100 companies or people against a written fit definition. Costs 0.05 credits per classified row. Staff, fit_classification flag.
POST /api/v1/fit-classifications. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
fit_definition is what a good fit looks like, in plain words (at most 4,000 characters).
rows is 1 to 100 objects, each with domain, name or description (free text about the company
or person), or a Kenso Search companyId or personId from search(operation="search-companies")
or search(operation="search-people"); not both ids. More than 100 rows is refused with the cap
in the message: split the list.
estimate_only=true returns the credit estimate and runs nothing. Use it before a large list.
Returns data.results in request order: index and status, which is classified (with fit, a
0-100 score and reason), not_found (a Kenso Search id with no record) or failed (with error;
send that row again). Each row first gets a fit probability. A row with a clear one (below 0.3
or above 0.7) is decided by it: score is the probability times 100, fit is yes from 50 and no
below, and reason names the probability ("Fit probability 0.82"), not the facts. A row whose
probability is unclear (0.3 to 0.7) or missing falls back to a model that answers fit yes, no
or maybe, a score and a one-sentence reason; an unclear row that model does not answer keeps
the probability's verdict. data.succeeded and data.failed count them. data.estimate {credits, millicredits, creditsPerRow} is the cost when every row is
classified; data.charge {credits, millicredits} is what was charged. Only classified rows
cost credits. Not enough credits, or a person past their monthly credit limit, is a refusal
before any model call. Nothing is stored.
create
Write. POST https://api.ken.so/v1/model-configurations
Body (json): campaignId integer, flow string, maxTokens integer, model string, provider string, reasoningLevel string, temperature number
Create a model configuration for a campaign in the current workspace. Returns 201 and Location. Internal. Requires Campaigns edit.
POST /api/v1/model-configurations. Internal. Sends Ken-Version 1.1. A campaign outside the workspace is not_found before the write. flow is qualification, personalization, rewriting, segmentation, or scoring (tone_of_voice can be read and listed but not written). reasoning_level is none, minimal, low, medium, or high. Omit provider, max_tokens, temperature, and reasoning_level to leave the API defaults (max_tokens defaults to 2048 for qualification, segmentation and scoring, and to 4096 for personalization and rewriting).
delete
Write. DELETE https://api.ken.so/v1/model-configurations/{modelConfigurationId}
Path: modelConfigurationId
Delete a model configuration. Returns 204. A configuration outside the workspace is not_found. Internal.
DELETE /api/v1/model-configurations/{modelConfigurationId}. Internal.
Sends Ken-Version 1.1. Requires Campaigns edit.
ai-cost-estimate-get
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/ai-cost-estimate
Path: campaignId
Query: flow string, segmentId integer
Estimate prompt tokens and list the models a flow can use. flow is required. No currency amount. Internal.
GET /api/v1/campaigns/{campaignId}/ai-cost-estimate. Internal.
Sends Ken-Version 1.1. Requires Campaigns view.
flow is qualification, segmentation, personalization, or rewriting.
segment_id is optional. A campaign outside the workspace is not_found
before the reads. The payload has token counts, caching thresholds, and
supported models. It does not include a currency amount.
For the credit cost of a run, use billing operation credit-estimates-create.
ai-runs-get
Read. GET https://api.ken.so/v1/ai-runs/{aiRunId}
Path: aiRunId
Read one AI run. The id is a GUID. A missing run, or a run outside the workspace, is not_found. Public.
GET /api/v1/ai-runs/{aiRunId}. Public. Sends Ken-Version 1.1.
Requires Campaigns view. This is the poll for a run queued by models(operation="ai-runs-create").
Execute jobs stay GUIDs and are not numeric jobs.
get
Read. GET https://api.ken.so/v1/model-configurations/{modelConfigurationId}
Path: modelConfigurationId
Return one model configuration in the current workspace. A missing id, or one whose campaign is outside the workspace, is not_found.
GET /api/v1/model-configurations/{modelConfigurationId}. Internal.
Sends Ken-Version 1.1. Requires Campaigns view.
model-training-get
Read. GET https://api.ken.so/v1/model-training
Return whether the workspace's data may train Kenso's own model, with its basis and dates. Internal. Any member of the workspace. Read only: only a person signed in to Kenso changes it.
GET /api/v1/model-training. Internal (DEV-8810). Sends Ken-Version 1.1. The workspace is
X-Ken-Workspace-Id.
Returns {"success": true, "data": {"optedIn", "basis", "optedInAt", "historyFrom",
"optedOutAt", "updatedAt"}}. optedIn is true while the workspace's data may train Kenso's
own model. basis is why: opt_in (a workspace admin turned it on in Settings > Security),
rider (a signed rider, recorded by Kenso staff) or own (one of Kenso's own workspaces); it
stays the last consent's after an opt-out. optedInAt is when the consent started; historyFrom
(yyyy-MM-dd) is the first day whose data it covers, and while it is absent only data from
optedInAt on (no backdating). optedOutAt is when it was last turned off. Absent fields are
unset: a workspace that never set it reads {"optedIn": false}. Readable whatever the
model_training flag.
There is no MCP operation that changes it: the backend answers 403 agent_not_allowed to any
agent, MCP or API-key write. Tell the user to change it in Settings > Security themselves.
get-eligibility
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/ai-runs/eligibility
Path: campaignId
Query: flow string, preview string, segmentId integer
Read AI-run eligibility, with an optional invalidation preview. Pass flow and preview together to include the preview. Public.
GET /api/v1/campaigns/{campaignId}/ai-runs/eligibility. Public.
Sends Ken-Version 1.1. Requires Campaigns view.
preview is freshness or reset. When either flow or preview is set, both
are required. That flow is qualification, personalization, rewriting, or
segmentation. A campaign outside the workspace is not_found.
ai-line-holds-list
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/ai-line-holds
Path: campaignId
Query: cursor string, limit integer
List the contacts the AI line check held in a campaign, with the reasons and the held lines. Newest first, paged with limit and cursor. Public. Requires Campaigns view.
GET /api/v1/campaigns/{campaignId}/ai-line-holds. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. limit is 1 to 200 (default 50); pass
pagination.nextCursor as cursor for the next page while pagination.hasMore is true.
Each hold has contactId, reasons, heldAt and lines. reasons lists why the lines
were held, the first the main one: ungrounded (states a fact the lead's data does
not support), not_specific, tone (a phrase a person would not say), too_long.
lines are the lines the hold keeps for review, each with id, promptId, variable
(the prompt name), text, segmentId and stepOrder. A held contact sends nothing until
it is approved (models(operation="ai-line-holds-approve")) or regenerated, which
clears the hold and runs the check again: models(operation="ai-lines-regenerate",
contact_id=...) for one contact (ai-lines.regenerate), or
models(operation="reset", campaign_id=..., flow="personalization", contact_ids=[...])
for up to 500 (ai-runs.reset-contacts). A campaign outside the workspace is not_found.
ai-lines-list
Read. GET https://api.ken.so/v1/contacts/{contactId}/ai-lines
Path: contactId
List the AI lines a contact sends with: one per AI variable, the text its next send renders. Each line has id, promptId, variable, text, rewrite, segmentId, stepOrder. Public.
GET /api/v1/contacts/{contactId}/ai-lines. Public. Sends Ken-Version 1.1.
Requires Campaigns view. One line per AI variable of the contact's campaign, the
stored line the sequencer reads: the newest personalized line, or its rewrite
when the prompt rewrites (rewrite is then true), the segment's prompt before the
campaign's. Older runs and replaced lines are not listed. Ordered by variable, at
most 200 lines, not paginated. variable is the prompt name. A contact outside the
workspace, deleted, or not in a campaign is not_found, and so is every call while
the workspace's ai_line_edit flag is off.
byok-models-list
Read. GET https://api.ken.so/v1/byok-models
The models the workspace's own AI keys unlock (today Grok 4.7 on an xai or openrouter key), which Kenso offers only on those keys.
GET /api/v1/byok-models. Internal. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Any workspace member. Read only; it returns no key
material and no key status beyond which keys unlock a model. Keys are
managed only in the Kenso app (Settings > Integrations > Data & AI
providers).
Kenso runs these models only on the workspace's own key, never on its own:
with no usable key the model is not listed, and a saved pick of it runs
the flow's default model. Today the only one is grok-4.7 (Grok 4.7),
unlocked by an xai key or an openrouter key whose status is healthy,
unverified, no_credits or rate_limited (an invalid or removed key unlocks
nothing). Use the id it returns wherever a model id is picked.
Returns {success, data: [...]}, empty when nothing is unlocked. Each entry:
- id: the model id to pick, e.g. grok-4.7.
- label: display name, e.g. Grok 4.7.
- maker: the maker's provider slug, xai.
- keys: the workspace's provider keys that can run it, maker first
(xai, openrouter). A grok-4.7 call runs on the xai key first, then the
openrouter key.
- agents: true when Kenso's in-app agents (Ken chat, the Studio builder)
can run it too. That needs the xai key: an openrouter-only workspace
gets Grok 4.7 everywhere else but not in the agents.
Errors:
- 400 workspace_required: pass client_id.
- 404 not_found: the caller is not a member of that workspace.
- 503: the read failed; try again later.
Example: client_id=57
list
Read. GET https://api.ken.so/v1/model-configurations
Query: campaignId integer, cursor string, flow string, limit integer
List model configurations for a campaign in the current workspace. campaign_id is required. Optional flow narrows the page. Internal.
GET /api/v1/model-configurations. Internal. Sends Ken-Version 1.1. client_id is the workspace, sent as X-Ken-Workspace-Id. A campaign outside that workspace is not_found before the list is read. flow is qualification, personalization, rewriting, segmentation, tone_of_voice, or scoring. Requires Campaigns view.
ai-lines-regenerate
Write. POST https://api.ken.so/v1/contacts/{contactId}/ai-lines/regenerate
Path: contactId
Write a contact's AI lines again with a personalization run for that lead alone. Returns 202 and a GUID run id; poll models(operation="ai-runs-get"). Public.
POST /api/v1/contacts/{contactId}/ai-lines/regenerate. Public. Sends Ken-Version 1.1.
Requires Campaigns edit and the `ask` permission. Clears the lead's personalized lines (and the rewritten lines
built on them), then queues the run. Uses credits: one personalization row (300
credits per 1,000 rows). A lead already sent or exported, with an email queued to
send, or in an unfinished AI run is 409 invalid_state and nothing changes. An AI
quota limit is 429 and too few credits 402, both before anything is cleared, so
the lead keeps its lines. Only a full AI run queue (503) after the clear leaves
the lead without lines until a retry or the next scheduled AI run. Ask the user
first when they did not ask for new lines.
reset
Write. POST https://api.ken.so/v1/campaigns/{campaignId}/ai-runs/reset
Path: campaignId
Body (json): flow string
Reset an AI flow and the flows that depend on it, for a campaign or chosen contacts. DESTRUCTIVE: deletes AI results (credit-funded) with no confirm step. Public route. Needs edit access to campaigns. A campaign outside the workspace is not_found.
POST /api/v1/campaigns/{campaignId}/ai-runs/reset. Public. Sends Ken-Version 1.1.
Needs edit access to campaigns (the catalog requirement). It deletes the flow's AI
responses and qualification or segmentation results, does the same for the flows
that depend on it, and cancels in-flight provider batches. Ask the user before
calling it. flow is qualification, personalization, rewriting, or
segmentation; any other flow (tone_of_voice, scoring) is refused before the
call. Without contact_ids the whole campaign is reset.
contact_ids (1 to 500 ids) resets only those contacts, so a lead whose context
changed gets fresh lines on the next run. It calls
POST /api/v1/campaigns/{campaignId}/ai-runs/reset-contacts instead, never the
campaign-wide route. flow must then be personalization (which also resets
rewriting) or rewriting. Nothing campaign-wide is cancelled. The result adds
contactsReset and contactsSkipped ({contactId, reason}); reason is
not_in_campaign, sent_or_exported (already sent or exported, left as is),
queued_to_send (an email is queued to send; reset it after the send or after
pausing the campaign) or in_flight (inside an active AI batch, reset it after
the batch lands). An API without contact resets answers not_found and resets
nothing.
ai-lines-update
Write. PATCH https://api.ken.so/v1/contacts/{contactId}/ai-lines/{aiLineId}
Path: contactId, aiLineId
Body (json): text string
Replace the text of one of a contact's AI lines. The lead's next send uses it. Public. Requires Campaigns edit. Free: no AI run.
PATCH /api/v1/contacts/{contactId}/ai-lines/{aiLineId}. Public. Sends Ken-Version 1.1.
Take ai_line_id from ai-lines-list. text is 1 to 4,000 characters; it gets the
cleanup a generated line gets (emoji removed, dashes normalized, spaces collapsed)
and must be at most 1,000 characters after it, else validation_failed. Steps
already sent keep what they sent. An approval draft showing the lead is updated.
Another of the contact's lines that the send does not read (an older run, a
personalized line its rewrite replaces) is 409 invalid_state and nothing changes:
list the lines again and edit the one shown. A line that is not the contact's is
not_found.
update
Write. PATCH https://api.ken.so/v1/model-configurations/{modelConfigurationId}
Path: modelConfigurationId
Update a model configuration. Absent fields stay unchanged. JSON null clears provider. Internal. Requires Campaigns edit.
PATCH /api/v1/model-configurations/{modelConfigurationId}. Internal.
Sends Ken-Version 1.1. A configuration outside the workspace is not_found
before the write. changes uses snake_case or camelCase field names.
ai_supported_models
Read.
List the provider-neutral AI models that the backend allows for a given flow. Client-facing: catalog list only (include_vendors=False); vendor internals blocked.
List the provider-neutral AI models that the backend allows for a given flow.
Client-facing sub-surface (task 15): the catalog list only. include_vendors=True
(provider groups / vendor failover internals) is rejected for non-staff on the
client-facing host. Staff and the internal host keep the full response.
By default this tool returns only logical model names in `models` and
`defaultModel`. Provider routing is owned by the backend provider-chain and
batch failover tables. Operator workflows that need to inspect provider groups
can pass `include_vendors=True`; normal campaign setup should leave it false
and save only the logical `model`.
The catalog changes over time as providers and models are added or retired.
Always call this tool to get the current list rather than hardcoding model IDs;
the example payload below is illustrative, not authoritative.
Qualification (flow 1), Segmentation (flow 4), and Scoring (flow 6) execute
as Jev (Vercel AI Gateway model typesafe-ai/jev, Typesafe direct as backup).
A saved chat model on flows 1 and 4 is stored and ignored. Personalization
and Rewriting still use this catalog.
Endpoint:
---------
GET /api/v1/ai/flows/{flow}/supported-models
Parameters:
-----------
client : KenAPIClient
API client instance
flow : int or str
AI workflow to look up. Accepts either the numeric ID used by the rest of
the MCP (1=Qualification, 2=Personalization, 3=Rewriting, 4=Segmentation)
or the name string ("Qualification", "Personalization", "Rewriting",
"Segmentation"). Flow 5 (ToneOfVoice) is not configurable and not
accepted here.
include_vendors : bool, optional
Defaults to False. When False, provider fields are stripped from the
returned payload and old provider-specific model rows are defensively
de-duped into logical model names. When True, the raw backend response is
returned with `providerGroups` for operator/vendor diagnostics.
Returns:
--------
dict
API response shaped like:
{
"success": true,
"flow": "Personalization",
"defaultModel": "kimi-k2.5",
"maxTokens": 500,
"temperature": 0.6,
"models": [
{"id": "deepseek-v4-flash", "label": "deepseek-v4-flash"},
{"id": "deepseek-v4-pro", "label": "deepseek-v4-pro"},
{"id": "kimi-k2.6", "label": "kimi-k2.6"},
{"id": "kimi-k2.5", "label": "kimi-k2.5"},
...
]
}
With include_vendors=True, the raw backend response may also include:
{
"providerGroups": [ # read this for vendor-aware UIs
{
"provider": "Moonshot",
"models": [
{"id": "kimi-k2.6", "label": "kimi-k2.6"}
]
},
{
"provider": "Doubleword",
"models": [
{"id": "doubleword/kimi-k2.6", "label": "kimi-k2.6"}
]
},
{
"provider": "DeepSeek",
"models": [
{"id": "deepseek-v4-pro", "label": "deepseek-v4-pro"}
]
}
]
}
Only Moonshot, Doubleword, DeepSeek, Meta, ExperientialLabs and Hemmingway
are currently selectable. OpenAI,
Anthropic, xAI, OpenRouter, TogetherAi and FireworksAi are temporarily
omitted from providerGroups and rejected by MCP overrides - their
accounts have no credit and return HTTP 402. The backend also remaps any
persisted config pointing at one of them onto the flow default at run
time, so a config naming them would not run on them anyway.
Exception: grok-4.7 (x-ai/grok-4.7 on OpenRouter) is listed and selectable
only when the workspace's own xAI or OpenRouter key unlocks it.
Save `model` as the logical name shown in the default response. If an operator
needs to force one backend vendor for a diagnostic or migration, pass the
optional `vendor` override to `prompts(operation="ai_variables_save")` using one of the
currently selectable enum names.
Examples:
---------
- `models(operation="ai_supported_models", flow="Qualification")`
- `models(operation="ai_supported_models", flow=2)` # Personalization
ai_token_analysis
Read.
Get token count analysis for a campaign's AI prompt by flow.
Get token count analysis for a campaign's AI prompt by flow.
This mirrors the backend token analysis endpoint and returns the exact
token-count breakdown the frontend uses to reason about prompt caching.
The authenticated user must have access to the requested campaign; the
backend rejects cross-tenant campaign IDs before analyzing prompt content.
Endpoint:
---------
GET /api/v1/ai/campaigns/{campaign_id}/token-analysis/{flow}
Parameters:
-----------
client : KenAPIClient
API client instance
campaign_id : int
Campaign ID to analyze
flow : str
One of: "Qualification", "Personalization", "Rewriting", "Segmentation"
Unsupported backend flows, including ToneOfVoice, are validation errors.
segment_id : int, optional
Campaign segment ID for Personalization/Rewriting analysis. If omitted,
the backend resolves the campaign's active default segment for
Personalization and Rewriting and uses that same segment for both
sequence context and prompt selection. If no active default segment
exists, segmented analysis returns no prompt segments instead of
silently falling back to campaign-level prompt or sequence context.
Returns:
--------
dict
API response with:
- success: backend success flag
- flow: name of the flow analyzed
- provider: AI provider resolved for this campaign + flow
- model: AI model resolved for this campaign + flow
- totalSystemPromptTokens: sum of all returned prompt segments
- minimumForCaching: top-level minimum used by the backend response
- meetsCachingThreshold: overall caching result. For Rewriting, this is
true only when every cacheable segment individually meets its minimum
(with the current single-segment shape that reduces to the lone segment
meeting its minimum).
- segments: per-segment token breakdown, each including:
- name
- tokenCount
- cacheTtl
- minimumForCaching
- meetsCachingThreshold
Per-flow segment shape:
-----------------------
The backend returns a single prompt segment per flow:
- Qualification: one "System Prompt" segment.
- Segmentation: one "System Prompt" segment.
- Personalization: one "Personalization (Instructions + Rules + Context + Variables)"
segment that combines instructions, rules, company context,
voice, audience, email sequence, and variables.
- Rewriting: one "Combined Rewriting Prompt" segment that combines the
default rewriting prompt, deliverability, context, sequence,
and custom instructions.
Personalization details:
------------------------
The personalization audience description is resolved by the backend from:
1. Qualification prompt AudienceDescription
2. Default segment description
The email sequence context includes all non-deleted A/B/C/D variants for
each step in stable order.
Rewriting details:
------------------
The backend evaluates the caching threshold on the rewriting segment itself
rather than on a sum across multiple segments, so the segment-level
`meetsCachingThreshold` field is the source of truth when diagnosing cache
misses.
Examples:
---------
- `models(operation="ai_token_analysis", campaign_id=304, flow="Qualification")`
- `models(operation="ai_token_analysis", campaign_id=304, flow="Personalization")`
- `models(operation="ai_token_analysis", campaign_id=304, flow="Personalization", segment_id=165)`
- `models(operation="ai_token_analysis", campaign_id=304, flow="Rewriting", segment_id=165)`