AI runs
Queue AI runs over a campaign's contacts, check eligibility and reset flows or chosen contacts.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
Start an AI run
/v1/campaigns/{campaignId}/ai-runsai-runs.create- Permission
- Campaigns edit and the
askpermission - Credits
- 50 credits per 1,000 contact rows (
ai_qualification); 300 credits per 1,000 contact rows (ai_personalization) - Rate limit
- 30 requests a minute and 200 a day per workspace (Free plan: 3 a minute and 20 a day)
Queues a run of one flow over the campaign's eligible contacts and answers 202 with the run. Poll it until status is succeeded, failed or canceled. A refused run changes nothing. With dryRun: true it answers 200 with what the run would process. Personalization and rewriting run one segment at a time, so they need segmentId: start one run per segment.
Errors:
400 validation_failed: a body field is missing or not valid, such as nosegmentIdfor personalization or rewriting.402 plan_limit_reached: no credits are left.error.refusalhas the balance.404 not_found: the campaign is not in this workspace, orsegmentIdis not one of its segments.409 runs_on_agent: the workspace gave this flow to its own agent in the agent work settings, so Kenso's AI does not run it. Run it withkenso work run.429 rate_limited: an AI run quota is used up. Retry afterRetry-Afterseconds.503 service_unavailable: the run queue is full, or the workspace's agent work setting could not be read. Retry later.
Requires Campaigns edit and the ask permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign to process. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
flow | string | required | The flow to run: qualification, personalization, rewriting or segmentation. Required. |
batchSize | integer (int32) | optional | The most contacts this run processes, at least 1. Kenso lowers a value above the flow's limit to the limit: 2,000 for qualification and segmentation, 5,000 for personalization and 500 for rewriting. Omitted means 500, or the flow's limit when processAll is true. |
processAll | boolean | optional | True runs up to the flow's limit when batchSize is omitted. Default false. |
segmentId | integer (int64) | optional | A segment of the campaign, to process only its contacts. Required for personalization and rewriting, which run one segment at a time. Omit it for qualification and segmentation to run every segment. 0 is 400 validation_failed, not "no segment". |
provider | string | optional | The AI provider for this run only, such as openai or anthropic. Omitted uses the flow's saved model settings. Kenso ignores an override it cannot use, such as a model the provider does not offer for the flow, and runs the saved settings. |
model | string | optional | The AI model id for this run only. With no provider, Kenso picks the provider from the model. Omitted uses the flow's saved model settings. |
dryRun | boolean | optional | True checks the request and returns what the run would process (200) without queueing it, reserving quota or spending credits. Default false. |
curl -X POST "https://api.ken.so/v1/campaigns/812/ai-runs" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"flow": "qualification",
"batchSize": 1,
"processAll": true,
"segmentId": 812,
"provider": "openai",
"model": "string",
"dryRun": true
}'Response 200
Also answers 202. data is a AiRunDryRun.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an AI run
/v1/ai-runs/{aiRunId}ai-runs.get- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns a run's status. succeeded means Kenso handed the contacts to the AI provider, so results can land later. A run with no eligible contacts ends failed with error.
Errors:
404 not_found: no run has this id in this workspace, or it last changed over 24 hours ago.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
aiRunId | path | string (uuid) | required | The run id. |
curl -X GET "https://api.ken.so/v1/ai-runs/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a AiRun.
Show the 13 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a campaign's AI run eligibility
/v1/campaigns/{campaignId}/ai-runs/eligibilityai-runs.get-eligibility- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Returns, for each flow, how many contacts a run would process now and, when none would, the check that stops them. Send flow and preview together to also count what a reset or a new prompt would clear.
Errors:
400 validation_failed: a parameter is not valid, or only one offlowandpreviewis set.404 not_found: the campaign is not in this workspace, orsegmentIdis not one of its segments.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign to read. |
segmentId | query | integer (int64) | optional | A segment of the campaign, to count only its contacts. Omit it for every segment. 0 is 400 validation_failed, not "no segment". The preview always covers the whole campaign. |
flow | query | string | optional | The flow to preview: qualification, personalization, rewriting or segmentation. Send it with preview, or leave both out. |
preview | query | string | optional | What to preview: reset (what a reset of flow deletes) or freshness (what saving a new prompt for flow clears). Send it with flow, or leave both out. |
curl -X GET "https://api.ken.so/v1/campaigns/812/ai-runs/eligibility" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a AiRunEligibility.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Reset an AI flow
/v1/campaigns/{campaignId}/ai-runs/resetai-runs.reset- Permission
- Campaigns edit
- Rate limit
- 10 requests a day per workspace (Free plan: 1 a day)
Clears a flow's output, and every later flow's, for every contact of the campaign, emailed or not, and cancels those flows' running batches. The next AI run processes the contacts again. A segmentation reset also moves every contact to the default segment. Each reset counts against a daily quota.
Errors:
400 validation_failed:flowis not valid, or a segmentation reset finds no default segment.404 not_found: the campaign is not in this workspace.429 rate_limited: the daily reset quota is used up. Retry afterRetry-Afterseconds.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The campaign to reset. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
flow | string | required | The flow to reset: qualification, personalization, rewriting or segmentation. Kenso also resets every flow after it. Required. |
curl -X POST "https://api.ken.so/v1/campaigns/812/ai-runs/reset" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"flow": "qualification"
}'Response 200
data is a AiRunReset.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Reset an AI flow for chosen contacts
/v1/campaigns/{campaignId}/ai-runs/reset-contactsai-runs.reset-contacts- Permission
- Campaigns edit
- Rate limit
- 4,800 requests a minute per API key
Clears the listed contacts' personalization or rewriting output, so the next AI run writes their lines again. Kenso skips a contact that is not in the campaign, was already sent or exported, has a send queued or is in an unfinished AI batch, and lists it in contactsSkipped. It uses no reset quota.
Errors:
400 validation_failed:floworcontactIdsis not valid.404 not_found: the campaign is not in this workspace.
Requires Campaigns edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | path | integer (int64) | required | The contacts' campaign. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
flow | string | required | The flow to reset: personalization (its rewritten lines too) or rewriting. Required. |
contactIds | array of integer (int64) | required | The contacts to reset, 1 to 500 contact ids of the campaign. Required. |
curl -X POST "https://api.ken.so/v1/campaigns/812/ai-runs/reset-contacts" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"flow": "string",
"contactIds": [
812
]
}'Response 200
data is a AiRunReset.
Show the 12 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in AI:AI linesAI line holdsAutonomous repliesAgent work settingsAgent permissionsAgent workAgent sandbox connectionsAgent sandbox runsAgent sandbox automatic runsAI feedbackAll resources