Skip to Content
AI

AI runs

Queue AI runs over a campaign's contacts, check eligibility and reset flows or chosen contacts.

AI5 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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-Idheaderinteger (int64)optionalThe 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

POST/v1/campaigns/{campaignId}/ai-runsai-runs.create
Permission
Campaigns edit and the ask permission
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)

Try it on developer.ken.so

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 no segmentId for personalization or rewriting.
  • 402 plan_limit_reached: no credits are left. error.refusal has the balance.
  • 404 not_found: the campaign is not in this workspace, or segmentId is 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 with kenso work run.
  • 429 rate_limited: an AI run quota is used up. Retry after Retry-After seconds.
  • 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

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredThe campaign to process.

Request body

application/json, optional.

FieldTypeRequiredDescription
flowstringrequiredThe flow to run: qualification, personalization, rewriting or segmentation. Required.
batchSizeinteger (int32)optionalThe 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.
processAllbooleanoptionalTrue runs up to the flow's limit when batchSize is omitted. Default false.
segmentIdinteger (int64)optionalA 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".
providerstringoptionalThe 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.
modelstringoptionalThe 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.
dryRunbooleanoptionalTrue checks the request and returns what the run would process (200) without queueing it, reserving quota or spending credits. Default false.
Request
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

GET/v1/ai-runs/{aiRunId}ai-runs.get
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
aiRunIdpathstring (uuid)requiredThe run id.
Request
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

GET/v1/campaigns/{campaignId}/ai-runs/eligibilityai-runs.get-eligibility
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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 of flow and preview is set.
  • 404 not_found: the campaign is not in this workspace, or segmentId is not one of its segments.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredThe campaign to read.
segmentIdqueryinteger (int64)optionalA 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.
flowquerystringoptionalThe flow to preview: qualification, personalization, rewriting or segmentation. Send it with preview, or leave both out.
previewquerystringoptionalWhat 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.
Request
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

POST/v1/campaigns/{campaignId}/ai-runs/resetai-runs.reset
Permission
Campaigns edit
Rate limit
10 requests a day per workspace (Free plan: 1 a day)

Try it on developer.ken.so

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: flow is 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 after Retry-After seconds.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredThe campaign to reset.

Request body

application/json, optional.

FieldTypeRequiredDescription
flowstringrequiredThe flow to reset: qualification, personalization, rewriting or segmentation. Kenso also resets every flow after it. Required.
Request
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

POST/v1/campaigns/{campaignId}/ai-runs/reset-contactsai-runs.reset-contacts
Permission
Campaigns edit
Rate limit
4,800 requests a minute per API key

Try it on developer.ken.so

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: flow or contactIds is not valid.
  • 404 not_found: the campaign is not in this workspace.

Requires Campaigns edit.

Parameters

NameInTypeRequiredDescription
campaignIdpathinteger (int64)requiredThe contacts' campaign.

Request body

application/json, optional.

FieldTypeRequiredDescription
flowstringrequiredThe flow to reset: personalization (its rewritten lines too) or rewriting. Required.
contactIdsarray of integer (int64)requiredThe contacts to reset, 1 to 500 contact ids of the campaign. Required.
Request
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.


On this page