Qualify Runs qualify_runs
Qualify every match of a Kenso Search people or companies search against a written fit definition, in the background (up to 5,000 rows, 0.05 credits a classified row): create (estimate_only=true first for the cost), get to poll, list-rows for the verdicts, cancel. For a short list of rows use models(operation="fit-classifications-create"). Needs the fit_classification feature.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through qualify_runs_read and changes through qualify_runs_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: cancel, create, get, list, list-rows
cancel
Write. Early access: needs fit_classification on for the workspace. POST https://api.ken.so/v1/fit-classification-runs/{runId}/cancel
Path: runId
Stop a queued or running whole-search qualification run. Staff, fit_classification flag.
POST /api/v1/fit-classification-runs/{runId}/cancel. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
The run becomes cancelled. A page being classified when the call lands is still stored and
charged, and the verdicts so far stay readable. A finished run comes back as it is.
create
Write. Early access: needs fit_classification on for the workspace. POST https://api.ken.so/v1/fit-classification-runs
Body (json): estimateOnly boolean, fitDefinition string, maxRows integer, searchFilters any JSON, searchType string
Qualify every match of a Kenso Search people or companies search, in the background. Costs 0.05 credits per classified row, charged a page at a time. Staff, fit_classification flag.
POST /api/v1/fit-classification-runs. 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).
search_type is people or companies. search_filters is the request body that
search(operation="search-people") or search(operation="search-companies") takes as body;
its page, pageSize and searchAfter keys are ignored. A lookalike search is refused
(lookalike_not_storable): classify its rows with models(operation="fit-classifications-create").
max_rows caps the run, 1 to 5,000 (default 5,000).
Kenso counts the matches first: data.totalMatches is the search's count, data.rows the count
capped by max_rows, and data.estimate {credits, millicredits, creditsPerRow} is rows times 0.05
credits. estimate_only=true returns only that (status estimate, id null) and creates nothing:
call it first and show the cost. Otherwise the run is queued (status queued, HTTP 202) and runs
in the background 100 rows a page, each row classified as models(operation=
"fit-classifications-create") classifies it. Poll qualify_runs(operation="get", run_id=...)
until status is completed, stopped (credits ran out: stopReason insufficient_credits or
credit_limit; or feature_off; the verdicts so far are kept), failed or cancelled. An error
service_unavailable means Kenso Search did not answer or whole-search runs are paused: nothing
was created.
Nothing is added to a campaign or list. Read the keepers with qualify_runs(operation=
"list-rows", run_id=..., fit="yes") and import their personId values with
saved_searches(operation="import_to_campaign", ...).
One run per workspace at a time: a second create is refused (conflict) while one is queued or
running.
get
Read. Early access: needs fit_classification on for the workspace. GET https://api.ken.so/v1/fit-classification-runs/{runId}
Path: runId
Get one whole-search qualification run: status, progress, verdict counts and credits. Staff, fit_classification flag.
GET /api/v1/fit-classification-runs/{runId}. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
data: id, status (queued, running, completed, stopped, failed or cancelled), stopReason
(insufficient_credits, credit_limit, feature_off, search_rejected, service_unavailable or
null), message,
searchType, fitDefinition, totalMatches (the search's count), rows (the most the run
classifies), processed, kept, dropped, unsure, notClassified (not charged), estimate and charge
{credits, millicredits}, createdAt, updatedAt and finishedAt. A run of another workspace is
not_found.
list
Read. Early access: needs fit_classification on for the workspace. GET https://api.ken.so/v1/fit-classification-runs
Query: cursor string, limit integer
List the workspace's whole-search qualification runs, newest first. Staff, fit_classification flag.
GET /api/v1/fit-classification-runs. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. limit is 1 to 50 (default 20). cursor is the previous page's pagination.nextCursor. Each run is what qualify_runs(operation="get") returns.
list-rows
Read. Early access: needs fit_classification on for the workspace. GET https://api.ken.so/v1/fit-classification-runs/{runId}/rows
Path: runId
Query: cursor string, fit string, limit integer
List a run's rows with their verdicts: keepers, drops with reasons, unsure, not classified. Staff, fit_classification flag.
GET /api/v1/fit-classification-runs/{runId}/rows. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
fit narrows the rows: yes (keepers), no (drops), maybe (unsure) or none (not classified, not
charged). Omit it for every row. Rows come in search order. limit is 1 to 200 (default 50);
cursor is the previous page's pagination.nextCursor, sent with the same fit.
A row: position, personId or companyId, name, title and companyName (a person), domain,
status (classified, not_found or failed), fit, score (0-100) and reason. Import keepers'
personId values with saved_searches(operation="import_to_campaign", ...).