Approvals approvals
approval-tests-create makes an approval draft from a saved search (saved_search_id) or filters. Placement tests are created and listed here; one test's results are analytics placement-tests-get (test_id).
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through approvals_read and changes through approvals_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: advance, approval-tests-create, placement-tests-create, shares-create, approval-tests-feedback, get, shares-get, approval-tests-list, placement-tests-list, shares-list, shares-preview-draft, shares-remind, shares-revoke, rotate-link, shares-update, create_approval_test, get_approval_test, rotate_approval_link, summary
advance
Write. POST https://api.ken.so/v1/approval-tests/{approvalTestId}/advance
Path: approvalTestId
Body (json): batchSize integer, flow string, segmentId integer
Advance an approval draft through one AI flow. Internal. Requires Campaigns edit. flow is lowercase snake_case.
POST /api/v1/approval-tests/{approvalTestId}/advance. Internal.
Sends Ken-Version 1.1. Requires Campaigns edit. flow is qualification,
segmentation, personalization, or rewriting. personalization and rewriting
require segmentId. batchSize is optional. A draft outside the workspace is
not_found before the advance.
approval-tests-create
Write. POST https://api.ken.so/v1/campaigns/{campaignId}/approval-tests
Path: campaignId
Body (json): autoStartWorkflows boolean, contactLimit integer, contacts array, filters any JSON, filtersJson any JSON, generationMode string, savedSearchId string, savedSearchName string, source string, sourceCampaignId integer
Create an approval draft on a campaign. Internal. Requires Campaigns edit and the `share` permission. Returns the created draft.
POST /api/v1/campaigns/{campaignId}/approval-tests. Internal. Sends Ken-Version 1.1.
Requires Campaigns edit and the `share` permission. The workspace is X-Ken-Workspace-Id. The API returns 201.
contactLimit is 1 to 100. Omit it for the server default of 20. generationMode
is realtime or batch. batch is forbidden unless the caller is SuperAdmin.
source is savedSearch, fileUpload, or fromCampaign. fromCampaign requires
sourceCampaignId. filters_json is the saved search's filters, a JSON object or
a JSON string, sent as given. A campaign outside the workspace is not_found
before create.
placement-tests-create
Write. POST https://api.ken.so/v1/placement-tests
Body (json): body string, campaignId integer, campaignSegmentId integer, contactId integer, control boolean, domainId integer, followUp object, inboxId integer, openPixel boolean, randomCopyVersion boolean, randomLead boolean, randomScope boolean, randomSegment boolean, sampleVariables object, sequenceVersionId integer, subject string, trackLinks boolean
Start an inbox placement test from an inbox, a domain or a campaign's senders. Returns 201. Sends test email to seed inboxes; results in about an hour. Read domain_setup(operation="placement-tests-availability") first.
POST /api/v1/placement-tests. Sends Ken-Version 1.1. Requires Delivery edit. Listed to workspace
admins, and to every member with Delivery edit where placement_tests_public or placement_native is on.
Client seats cannot start one. The list, get and availability operations open with the same flags.
The backend picks the engine and checks the scope for it; this tool sends only the fields given.
Availability (read it first) says the engine, planAllowed, live providers, control and the tests left.
Kenso seed network (availability enabled: true; paid plans only):
- Sends to 10 seed inboxes per provider (seedsPerArm). Google Workspace only at launch; Microsoft 365
joins when the network has enough seeds (availability providers[].active).
- Runs from any active inbox of the workspace. Scope: inbox_id tests one inbox, domain_id the domain's
inboxes, neither (with campaign_id alone) the campaign's senders. Not both inbox_id and domain_id.
random_scope is refused.
- Copy (one of the two is required): the campaign's (campaign_id; sequence_version_id, campaign_segment_id,
contact_id and the random_* choices pick which copy and lead), or custom subject and body together, which
need no campaign.
- control=True adds the copy check: a second, neutral message from the same senders, to tell a copy
problem from a domain problem. Only where availability control.available is true.
- open_pixel=True is refused: opens are not tracked.
- track_links=False sends the links as written, untracked (default True).
- follow_up={"body", "format": "plain"|"html", "delay_minutes": 5-4320, "subject"?} sends each seed a reply in the
first email's thread after the delay. Its scope stays busy until it is read: compare follow-ups from two inboxes.
- Results in about an hour (placement-tests-get progress.finalBy). The verdict line explains the likely
cause: read verdict.summary first and show it as is.
- Budget: 10 a day and 60 in 30 days on paid plans, 2 a day and 8 in 30 days while trialing, and 3 a day
per sending inbox. Retests and weekly tests do not count toward the workspace's daily limit; only tests
people start do. Kenso staff have a daily cap instead.
- Answers 201 with the new test, or 200 with the test already pending or running for that scope, whatever
its copy, control, pixel or links: compare its subject and body with yours. Under replica lag the 201 body
can carry only the test's own fields (no progress, providers or seeds): read
analytics(operation="placement-tests-get", test_id=...) for progress.
Refusals (HTTP and error.code; pass error.details through, it can carry field, code and inboxId):
- 400 validation_failed: one details entry names the field (both inbox_id and domain_id, random_scope,
only one of subject and body, or no campaign_id where the copy or the scope needs one), or open_pixel=True
(details code open_tracking_unavailable).
- 402 plan_limit_reached with error.refusal: the workspace is on no paid plan. Tell the user it needs one.
- 404 not_found: the campaign, inbox or domain is not in this workspace.
- 409 demo_workspace; 409 control_unavailable (not enough seeds for the copy check: retry without
control); 409 invalid_state with details code sender_unavailable (no inbox can send), or
placement_test_starting (a test for this scope is starting: try again in a minute).
- 422 with the problem as the code, to fix before a retry: copy_unresolved, copy_not_neutral,
copy_link_listed, copy_too_large, copy_brand_domain, copy_has_attachments, sender_blocked (details code
is the block reason, unspecified when blank). A refusal
on one sender's filled copy names that inboxId in details.
- 429 quota_exceeded: the workspace budget, with Retry-After; do not retry before then, tell the user.
429 rate_limited with details code sender_daily_cap (an inbox's 3 a day; also when a domain's or
campaign's senders all drop for mixed reasons) or staff_daily_cap.
- 503 seed_network_busy, link_check_unavailable or placement_native_paused (Kenso tests paused): try later.
Older engine (availability enabled: false, Kenso not paused): campaign_id is required, with exactly one
of domain_id or inbox_id, or random_scope=True (picks an eligible domain in the workspace and ignores
both). control, subject, body, track_links and follow_up are ignored. It sends only from active mailboxes Kenso bought for the workspace.
Budget per workspace: 20 a day and 50 in 30 days (5 a minute; a Free plan gets 1 a minute, 2 a day
and 5 in 30 days). Where placement_tests_public is on, 2 a day and 8 in 30 days on every plan. Over it is
429: where that flag is on the refusal names the limit and its window ("This workspace reached its limit
of 2 placement tests in a day.") and when it resets. Do not retry before then; tell the user instead.
open_pixel=True uses link.<domain> or unsub.<domain> of the sending domain (the result's openPixelHost
names the host). 409 invalid_state when the workspace has no eligible domain, the campaign has no email
copy, or the workspace is a demo workspace, and with open_pixel when no pixel host serves on the domain
or the copy is plain text, and whenever a test with the other pixel setting is already running for the
campaign and domain. 503 service_unavailable: try again later. Neither uses up the budget.
Read the result with approvals(operation="placement-tests-list", campaign_id=...) (or inbox_id or
domain_id) and analytics(operation="placement-tests-get", test_id=...).
shares-create
Write. POST https://api.ken.so/v1/shares
Body (json): accountIds array, campaignId integer, company string, expiry string, holdLaunch boolean, items array, name string, permission string, recipients array, recurringReport boolean
Create a share link for a client to review. Freezes each item as it is now; returns 201 with url. Emails the link to recipients. approve + hold_launch holds the campaign's launch until approved.
POST /api/v1/shares. Public. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Requires Share edit and the `share` permission (Admin and Editor templates). 404 while the share flag is off. An OAuth connector needs the send consent scope, and workspace:admin for permission approve. items: one or more of leads, copy, settings, icp, report, plan. Each item's snapshot is frozen at create: later campaign edits do not change what the client sees. Create a new share to show newer work. copy is one item, leads one item per active segment; on an approve share they are the campaign's own external approval items, so approving them also clears the external approval launch gate. A campaign with no copy or no active segment answers 400 (items detail code empty). campaign_id: required unless items is only plan. account_ids: 1 to 100 accounts, required with plan (one account plan each). permission: view, comment or approve. It and items cannot change later. expiry: 7_days, 30_days (default) or never, counted from creation. recipients: up to 20 email addresses. Each gets the link by email now, and counts against the workspace's daily share email cap (200 by default, 20 on Free): past it the create answers 429, creates nothing and sends nothing. An address a share link email from this workspace reached in the last 24 hours is not emailed again: it is listed in data.alreadyEmailedRecipients, so send that person data.url yourself. An address that unsubscribed from this workspace's share emails (the link in every share email) is never emailed and does not count against the cap; data.unsubscribedRecipients lists it. hold_launch: needs approve and a leads, copy or settings item. The campaign does not launch until every item is approved. recurring_report: needs a report item. The share gets a fresh weekly report every Monday at 8 AM. name defaults to the campaign (or account) and the items shared; company (who it is for, shown on the page) defaults to the workspace name. Each is at most 255 characters. Returns data, the share with its detail fields (see shares-get). Send data.url to the client, or let recipients do it. Never build a share URL yourself.
approval-tests-feedback
Read. GET https://api.ken.so/v1/approval-tests/{approvalTestId}/feedback
Path: approvalTestId
Return the full feedback set for one approval draft. Internal. Requires Campaigns view. There is no cursor and no totalCount.
GET /api/v1/approval-tests/{approvalTestId}/feedback. Internal. Sends Ken-Version 1.1.
Requires Campaigns view. Feedback rows have no numeric id, so this returns the
full set. There is no cursor, no limit, and no totalCount. kind is lowercase
snake_case, including line_comment. A draft outside the workspace is not_found
before the feedback is read.
get
Read. GET https://api.ken.so/v1/approval-tests/{approvalTestId}
Path: approvalTestId
Return one approval draft. Internal. Requires Campaigns view. status is lowercase snake_case.
GET /api/v1/approval-tests/{approvalTestId}. Internal. Sends Ken-Version 1.1.
Requires Campaigns view. magicToken is null unless the caller also has
campaigns edit and the share feature. status is processing, ready, approved,
not_approved, or failed. progress.outcome is lowercase snake_case, including
needs_review. A draft outside the workspace is not_found.
shares-get
Read. GET https://api.ken.so/v1/shares/{shareId}
Path: shareId
Return one share link with its items, the client's decisions and comments, access rows and log. A missing, revoked or cross-workspace id is not_found.
GET /api/v1/shares/{shareId}. Public. Sends Ken-Version 1.1. Requires the share page.
Returns the list fields (see shares-list) plus:
items [{id, kind, title, status, approvalItemId, decidedAt, decidedByName,
decisionComment, commentCount}], item status approved, changes_requested,
not_reviewed, view_only or changed; comments [{id, shareItemId, anchor, body,
authorName, createdAt}], oldest first; access [{label, value}], the rows the page
shows ("They can", "Expires", "Launch", "Repeats", "Branding"); activity [{id, type,
shareItemId, actorKind, actorName, actorUserId, data, createdAt}], newest first, at
most 50. actorKind is user, reviewer or system. url follows the shares-list rule.
approval-tests-list
Read. GET https://api.ken.so/v1/campaigns/{campaignId}/approval-tests
Path: campaignId
Query: cursor string, limit integer
List a campaign's approval drafts, ordered by draft number. Internal. Requires Campaigns view. There is no totalCount.
GET /api/v1/campaigns/{campaignId}/approval-tests. Internal. Sends Ken-Version 1.1.
Requires Campaigns view. magicToken is null unless the caller also has
campaigns edit and the share feature. The workspace is X-Ken-Workspace-Id.
Ordered by draft number. limit is 1 to 200 and cursor pages that order.
Omit limit for the server default. There is no totalCount. status is lowercase snake_case:
processing, ready, approved, not_approved, or failed. A campaign outside
the workspace is not_found before the list. Legacy approval-test tools stay.
Repair stays POST /v1/admin/approval-tests/repair on the staff tool.
placement-tests-list
Read. GET https://api.ken.so/v1/placement-tests
Query: campaignId integer, cursor string, domainId integer, domainIds string, inboxId integer, limit integer
List placement tests of one campaign, inbox or domain, or of several domains, newest first. Internal. Exactly one of campaign_id, inbox_id, domain_id or domain_ids. Rates are fractions from 0 to 1.
GET /api/v1/placement-tests. Internal. Sends Ken-Version 1.1. Requires Delivery view.
Listed to workspace admins, and to every member with Delivery view where placement_tests_public or
placement_native is on.
Give exactly one of campaign_id, inbox_id, domain_id or domain_ids. A campaign's list holds the tests started
for the campaign and the weekly tests of the domains it sends from (even a weekly test another campaign owns).
An inbox's list holds the tests of that inbox (its scope or one of its senders), and a domain's list the tests
of that domain, from any campaign and either engine. A campaign, inbox or domain outside the workspace is
not_found before the query runs.
domain_ids reads several domains in one call: 1 to 50 domain ids. Each domain gets its newest `limit` tests
(the first page domain_id gives it), grouped by domain in the order of domain_ids, each newest first. With
domain_ids, limit is the tests per domain: 1 to 20, and 20 when omitted. An id
outside the workspace, or a deleted domain, has no items instead of not_found. It takes no cursor and has no
further pages (pagination.hasMore is false): page through one domain's older tests with domain_id.
Default sort is -createdAt. limit is 1 to 200. Omit it for 50 (with domain_ids: 1 to 20, default 20).
status is snake_case. inboxRate, spamRate, categoryRate, and missingRate are fractions, omitted until the
test completes.
provider is the stored testing provider (omitted when none); providerKind is its neutral name: kenso,
mailbox_provider or other. A Kenso test (seed network) has provider "kenso" and adds:
- scope: inbox, domain or campaign (the campaign's senders).
- verdict: {cause, summary}, once the test completes. cause is auth_failing, copy, reputation,
microsoft_bulk, one_provider, healthy or mixed. summary is one sentence: show it as is.
- hasControl: true when the test also sent the plain control message (the copy check).
- trackLinks: false when the test sent its links as written, untracked.
- providersTested: the seed providers it sent to, such as ["google_workspace"].
dataPoints is one breakdown. Stored folder counts map to googlePersonal,
googleWorkspace, outlookPersonal, and outlookWorkspace, each a fraction from
0 to 1. A name is omitted when that provider was not stored. Rows without
folder counts omit dataPoints entirely.
For results by provider, sender and seed, read
analytics(operation="placement-tests-get", test_id=...).
shares-list
Read. GET https://api.ken.so/v1/shares
Query: accountId integer, campaignId integer, cursor string, limit integer, status string
List the workspace's share links (client review links), newest first. Revoked shares are left out. Filter by campaign, account (shares with its plan) or review status.
GET /api/v1/shares. Public. Sends Ken-Version 1.1. client_id is sent as
X-Ken-Workspace-Id. Requires the share page. 404 while the share flag is off.
status (comma = OR): not_opened, viewed, n_of_m_approved, changes_requested,
approved. limit 1 to 200 (default 50). Pass pagination.nextCursor back unchanged
as cursor while pagination.hasMore is true.
Returns data (shares without the detail fields), pagination {nextCursor, hasMore}
and changesRequestedCount: every live share with changes requested, whatever the
filters. Each share: id, name, company, url (the link to send), campaignId,
campaignName, accountIds, kinds, permission, expiry, expiresAt, isExpired,
holdLaunch, recurringReport, recipients, unsubscribedRecipients (the addresses in
recipients that unsubscribed from this workspace's share emails: Kenso sends them no
link, reminder or weekly report; only the recipient can undo it, with Resubscribe on
the unsubscribe page of any share email), status, approvedCount, kindCount,
changesRequestedCount, kindStatuses [{kind, status}], viewCount, firstViewedAt,
lastViewedAt, submittedAt, submittedByName, lastReportSentAt, createdByUserId,
createdAt, lastActivityAt. shares-get adds items, comments, access and log.
url comes only to a member with Share edit plus the share permission (Admin and
Editor templates): it lets its holder act as the client. An OAuth connector without
workspace:admin gets approve shares without url.
shares-preview-draft
Read. POST https://api.ken.so/v1/shares/preview
Body (json): accountIds array, campaignId integer, company string, expiry string, holdLaunch boolean, items array, name string, permission string, recipients array, recurringReport boolean
Show what a share would show the client before creating it. Saves nothing and emails no one. Takes the shares-create fields (no recipients) and returns the page the link would show.
POST /api/v1/shares/preview. Public. Sends Ken-Version 1.1. Requires Share edit and
the `share` permission. 404 while the share flag is off. Fields and their rules are
those of shares-create; a body create would refuse answers the same 400 or 404.
Each item is built now by the same snapshot builders create uses: copy rendered for
up to 5 sample leads (their custom variables and Ken's lines, "Not generated yet"
for a line not written yet), each active segment's lead list, the settings, ICP,
weekly report and account plans. Nothing is stored: run shares-create to make the link.
Returns data: brand, workspaceName, shareName, company, senderName, campaignName,
permission, expiresAt, holdLaunch, status, approvedCount, kindCount and items [{id,
kind, title, status, snapshot, comments}]. Item ids are 1, 2, ... in this preview
only. Items are not_reviewed (view_only for view and comment), except copy and lead
lists of an approve share whose version is already approved.
shares-remind
Write. POST https://api.ken.so/v1/shares/{shareId}/reminders
Path: shareId
Email the share link to every recipient again. Returns 202 with the count of addresses emailed. At most once per share every 24 hours. Emails each recipient email address (names never) that has not unsubscribed and that no share email from this workspace reached in the last 24 hours.
POST /api/v1/shares/{shareId}/reminders. Public. Sends Ken-Version 1.1. No body.
Requires Share edit and the `share` permission. Logs share_reminder_sent on the share.
Returns data {shareId, recipientCount, remindedAt, alreadyEmailedRecipients}: an address a
share link email from this workspace reached in the last 24 hours is left out and listed
there, and 429 recipients_emailed_today when that is every one. An address that
unsubscribed from this workspace's share emails is never reminded and not counted (see
unsubscribedRecipients on shares-get). 410 share_expired when the
share has expired (extend it with shares-update expiry first). 400 when it has
no recipients, 409 no_email_recipients when none of them is an email address (add
an address with shares-update recipients) or every email address unsubscribed. 429 when the share was reminded in the
last 24 hours, or when the workspace reached its daily share email cap (200 by
default): nothing is sent, and retrying sooner does not help. Sends X-Ken-Actor: agent. An OAuth
connector needs the send consent scope, and workspace:admin for an approve share.
shares-revoke
Write. DELETE https://api.ken.so/v1/shares/{shareId}
Path: shareId
Revoke a share link. The link stops working at once; this cannot be undone. Returns 204. Decisions the client already made stay. To share again, create a new share.
DELETE /api/v1/shares/{shareId}. Public. Sends Ken-Version 1.1. Requires Share edit
and the `share` permission.
After revoke the link answers 410 share_inactive, the share leaves shares-list,
and shares-get answers not_found.
rotate-link
Write. POST https://api.ken.so/v1/approval-tests/{approvalTestId}/rotate-link
Path: approvalTestId
Rotate an approval draft share-link token. Internal. Requires Campaigns edit and the `share` permission. The previous link stops immediately.
POST /api/v1/approval-tests/{approvalTestId}/rotate-link. Internal.
Sends Ken-Version 1.1. Requires Campaigns edit and the `share` permission. The workspace is
X-Ken-Workspace-Id. The response is the new magicToken. The previous link
stops immediately. A draft outside the workspace is not_found before rotate.
shares-update
Write. PATCH https://api.ken.so/v1/shares/{shareId}
Path: shareId
Body (json): company string, expiry string, holdLaunch boolean, name string, recipients array, recurringReport boolean
Change a share link's name, company, recipients, expiry, launch hold or weekly report. Absent fields stay. What is shared and the permission are fixed: create a new share to change them.
PATCH /api/v1/shares/{shareId}. Public. Sends Ken-Version 1.1. Requires Share edit
and the `share` permission.
Send at least one field.
recipients replaces the whole list (up to 20; [] clears it). New recipients are not
emailed: use shares-remind. Each email address it adds counts against the workspace's
daily share email cap (it gets later reminders and weekly reports): past it the
update answers 429 and changes nothing. An address that unsubscribed from this
workspace's share emails gets none of them and does not count against the cap. expiry is 7_days, 30_days or never, counted from creation, so
it can reopen an expired share. hold_launch needs an approve share with a leads,
copy or settings item; false lets the campaign launch without the client's approval.
recurring_report needs a report item. name and company are at most 255 characters;
name cannot be blank. Sends X-Ken-Actor: agent. An OAuth connector needs the send
consent scope, and workspace:admin to change recipients or expiry on an approve share.
Returns data, the share with its detail fields (see shares-get).
create_approval_test
Write.
Create a shareable external approval draft for a campaign. Resolves filters_json, imports the sample, and starts AI qual/seg/scoring when enabled. Batch personalization and rewriting still take ~8-12h: record the id, never re-create. Terminal status ends polling only; Batch usability needs the get readiness gates.
[API] Create a shareable external approval draft for a campaign.
This is the "Ask for external approval" action. It resolves the saved search
into a sample of contacts, then creates a draft: the backend duplicates the
campaign, imports those contacts, and starts the build. The draft comes back
in ``processing`` status. Poll ``approvals(operation="get_approval_test")``
with the returned ``id``, or list drafts with
``approvals(operation="summary")``.
**Terminal polling vs usability.** Terminal ``status`` / ``queueState``
(``ready`` / ``failed``, ``complete`` / ``failed``) means stop polling only.
For Batch and reverse-demo it does **not** prove the draft is usable or
shareable - an invalid Ready draft can still fail the readiness gates.
After the poll stops at terminal Ready, require the same canonical gates
documented by ``get_approval_test`` before treating Batch as usable:
- ``progress.outcome == "ready"``
- when ``progress.qualification.required > 0``:
``progress.qualification.qualified >= 1`` and both
``progress.qualification.pending`` and ``progress.qualification.failed``
are zero
- when ``progress.segmentation.required > 0``: both
``progress.segmentation.pending`` and ``progress.segmentation.failed``
are zero
- when ``progress.personalization.required > 0``:
``progress.personalization.fullyPersonalized >= 1`` (one fully
personalized contact is sufficient) and
``progress.personalization.pending`` / ``failed`` / ``partial`` are all zero
- when ``progress.rewriting.required > 0``:
``progress.rewriting.pending`` / ``failed`` / ``partial`` are all zero
Call ``describe_tools(["approvals"])`` (``get_approval_test``) for the canonical
readiness semantics rather than re-deriving them from create/status alone.
When ``progress`` is missing or a required gate fails after terminal Ready,
do not approve or share: wait for a progress-bearing replica or route the
draft to needs-review / operator handling (one bounded retry where the
caller workflow allows it; never treat status-only Ready as success).
You pass the saved search's serialized ``filters_json`` (the same
``PeopleSearchFilters`` blob a saved people search stores). This tool runs the
people search itself (capped at ``contact_limit``) and forwards the resolved
rows as the draft's leads - exactly like the dashboard's "ask for approval"
flow. The filters must carry at least one real criterion; an empty/unfiltered
saved search is rejected rather than seeding the draft from arbitrary contacts.
Parameters
----------
campaign_id : int
The real (parent) campaign to build a draft of.
filters_json : str or dict
The saved search's ``filtersJson``, as a JSON object or a JSON string.
Required; the people search is run from it to resolve the draft's leads.
saved_search_id : str, optional
Opaque saved-search id for traceability/labeling only.
saved_search_name : str, optional
Human label of the saved search.
contact_limit : int
How many contacts to resolve + import (1..100, default 20; clamped
server-side).
generation_mode : {"realtime", "batch"}
Queue lane used to build the draft. Defaults to ``realtime``.
**Prefer ``batch`` for agent-driven or bulk External approvals drafts.**
Batch is a pooled build lane that runs its initial builds independently of the
Realtime lane interactive dashboard approvals use, and its Pending
backlog is durable and unbounded. Three ways that saves money: bulk
builds stop contending for interactive capacity, so nothing gets rebuilt
because it timed out behind other work; Batch applies stricter readiness
floors (zero qualified contacts, or zero fully personalized contacts,
resolve to ``needs-review`` instead of a hollow ``ready``), so an
unusable draft is caught before you pay for a second full AI rebuild.
Qualification, segmentation, and lead-quality scoring run
during the initial build on both realtime and batch, when the campaign
has those settings enabled. They do not wait for the provider drain.
Personalization and rewriting stay on the lane: batch still sends those
two through the provider Batch API rather than per-request calls, at
roughly half the per-token cost, in exchange for a time-to-Ready
measured in hours rather than minutes. Do not promise a specific
percentage or a specific completion time, and do not promise that the
whole External approvals draft is ready in seconds. Provider turnaround
for personalization and rewriting is not modelled.
Keep ``realtime`` only for a one-off External approvals draft a human is
waiting on live.
Batch requires a SuperAdmin identity. A forbidden or unsupported Batch
request is a hard stop: surface the error, never retry it as Realtime.
**Wall clock: a Batch draft is slow by design.** Realtime normally
reaches Ready in roughly 17-41 minutes. Batch normally takes roughly
**8-12 hours**, because personalization and rewriting are coalesced
and submitted on an 8-hourly drain. Qualification, segmentation, and
lead-quality scoring already ran during the initial build
when those settings are enabled; they are not on this drain.
Qualification and segmentation no longer wait on the old 01:00 / 09:00 /
17:00 drains. The remaining drains are staggered in pipeline order
(UTC): personalization 03:00 / 11:00 / 19:00, rewriting 04:00 / 12:00 /
20:00. A draft that just missed its stage's fire waits about 8 hours
for the next one, so long stretches with no visible movement are the
normal shape of this lane,
not a stall. The backend's own deadline for a Batch draft is 24 hours
(``ApprovalDraftQueue:BatchPipelineTimeoutMinutes``, 1440 minutes - the
same wall the Realtime lane gets); only past that does the pipeline
time out on its own. It was 7 days until 2026-07-31; a week-long wall
meant a dead provider chain surfaced as silence rather than a failure.
**Never re-create a Batch draft merely because it is slow.** A rebuild
duplicates the draft, spends the workspace's plan leads a second time,
and pays for the AI twice while the original keeps running. Record the
returned ``id``, stop, and come back later with
``get_approval_test`` (see its polling guidance). Escalate only on
a terminal failure or after the 24-hour deadline.
**Batch slots are released at initial build, not at Ready.** A Batch
draft holds an admission slot only until its initial build completes:
campaign duplication, lead import, and the AI sample for
qualification, segmentation, and scoring when those settings are
enabled. It then joins the post-build population waiting on coalesced
personalization and rewriting, and that population is uncapped by
design. Practically: a saturated ``batchActive`` is never a
reason to hold back work - it only means initial builds are busy.
``batchAwaitingAi`` is the field that tells you how much post-build
work is in flight.
Invariants - do not re-derive these:
- Creation is unbounded. The Pending backlog is durable and has no cap.
No capacity value on any endpoint can cause a create to be rejected.
- Creation IS rate-limited: 50 creates per minute, enforced at the
gateway and shared across all callers (not per client). Pace bulk
rebuilds; a 429 means slow down, not stop.
- Plan lead capacity applies: each draft's sample counts against the
workspace's remaining plan leads. Exhaustion returns a validation
refusal, which is a hard stop, not a retry.
- batchMaximumActive / batchAvailableCapacity are NOT quotas. They
bound concurrent initial builds (campaign duplication, lead import,
and the AI sample when those settings are enabled), and a Batch
draft frees its slot the moment that build ends.
batchAvailableCapacity=0 means "builds are saturated, your drafts are
queued and will run" - never "rejected". Branch on
batchAcceptingWork instead, which is always true.
- Never hard-code the lane size into a plan, a report, or a decision.
batchMaximumActive is operator-tunable and has already been raised
once. Read it live from admin_misc(operation="internal_approval_draft_queue") when you
genuinely need the number; that endpoint is the only accurate source.
client_id : int, optional
Tenant/workspace id to scope the people search to. Usually unnecessary
(the API key already scopes the search); pass it only when the saved
search must run against a specific client.
Returns
-------
dict
``{ "id", "status", "draftNumber", "queueState", "queuePosition",
"queuedAt", "buildStartedAt" }``. A durably accepted burst normally
starts with ``queueState="queued"``; ``queuePosition`` is a live fair-order
position and may change. Poll ``get_approval_test`` through
``building`` / ``processing`` until either terminal outcome:
``queueState="complete"`` (draft status ``ready``) or
``queueState="failed"`` (draft status ``failed``). Stop polling on either -
that ends the wait only. For Batch / reverse-demo, terminal Ready is not
usability: require ``progress.outcome == "ready"`` plus the required
qualification / segmentation / personalization / rewriting gates above
(canonical detail: ``describe_tools(["approvals"])``, ``get_approval_test``).
**Shareable link rules (create never returns a client URL)**
- Store only the draft ``id`` from this response. Do **not** write an
External approvals URL after create.
- Create returns ``id`` / status / queue fields only - **not** ``magicToken``
or ``magicLink``. There is no shareable client link yet.
- Never invent a URL from the draft id (e.g. ``/approvals/{id}`` or
``/approval/{id}``), and never write placeholders such as ``draft:658``,
``processing:draft-634``, or a fabricated token.
- After polling, take the link only from ``get_approval_test``:
use ``magicLink`` when present, else build solely as
``{app_base_url}/approvals/{magicToken}`` (plural ``approvals``) from that
response's token. While ``magicToken`` is null, there is no shareable link.
- ``status=ready`` alone is not enough to share for Batch / reverse-demo;
still require the readiness gates above.
Examples
--------
>>> await create_approval_test(
... campaign_id=311,
... filters_json='{"currentTitles":["CEO"],"industries":["SaaS"]}',
... saved_search_name="SaaS CEOs",
... contact_limit=20,
... generation_mode="batch",
... )
# Store only the returned draft id. Do NOT invent an approval URL.
# Then poll approvals(operation="get_approval_test") until terminal status/queueState.
# Stop polling there only - for Batch/reverse-demo still require
# progress.outcome == "ready" plus the required-stage gates above
# before treating the draft as usable (see describe_tools
# ["approvals"], get_approval_test). Missing progress or a failed gate ->
# needs-review / operator handling, not share/approve.
# Only when get returns magicToken/magicLink, use that magicLink
# (or {app}/approvals/{magicToken} - plural path only).
get_approval_test
Read.
Get one approval draft's status header (poll a processing build). Stop polling when status becomes ready or failed. Batch: require progress. Batch stays processing for ~8-12h - check back in hours, do not tight-loop.
[API] Get one approval draft's status header (poll a Processing build).
Use this after ``create_approval_test`` to watch a draft move from
``processing`` to terminal ``ready`` or ``failed``. Stop polling on either.
Once shareable, ``magicLink`` is the URL to send the client. For a
``notApproved`` draft, drill into the change requests with the approvals
operation ``approval-tests-feedback``.
**Polling cadence: Batch is an hours-long wait, not a tight loop**
A Realtime draft normally reaches terminal Ready in roughly 17-41 minutes.
A Batch draft (``generation_mode="batch"``) normally takes roughly
**8-12 hours**: personalization and rewriting are coalesced and submitted
on an 8-hourly drain. Qualification, segmentation, and lead-quality
scoring run during the initial build when those campaign
settings are enabled. There is no scoring readiness gate.
``progress.qualification`` and ``progress.segmentation`` are still the
gates for those two stages. Qualification and segmentation no longer wait
on the old 01:00 / 09:00 / 17:00 drains. The remaining drains are staggered
in pipeline order (UTC): personalization 03:00 / 11:00 / 19:00, rewriting
04:00 / 12:00 / 20:00. A draft that just missed its stage's fire waits
about 8 hours for the next one.
What that means for a caller:
- Do **not** block on a Batch draft and do **not** poll in a tight loop.
Record the ``id``, return control, and check back on the order of hours -
a few checks a day is plenty. Sub-minute polling only burns tokens and
the client's rate limit; it cannot make a drain fire sooner.
- ``status="processing"`` with ``queueState="processing"`` after many hours
is **normal for Batch**, not stuck and not a failure. Long stretches with
no visible movement are the expected shape of this lane.
- **Never re-create a Batch draft merely because it is slow.** A rebuild
duplicates the draft, spends the workspace's plan leads a second time,
and pays for the AI twice while the original keeps running.
- The backend's own deadline for a Batch draft is 24 hours
(``ApprovalDraftQueue:BatchPipelineTimeoutMinutes``, 1440 minutes - one
wall for both lanes since 2026-07-31, previously 7 days). Before that,
slowness is not evidence of a problem and is not a reason to escalate.
Only a terminal ``failed`` (read ``failureReason`` - see below,
``failed`` is not always fatal) or a draft past the 24-hour deadline is
worth an operator's attention. Because 8-12 hours is the typical
end-to-end time, a draft still processing at 24 hours is genuinely stuck
rather than merely slow.
**Shareable link rules (never invent URLs)**
Canonical shape: ``{app_base_url}/approvals/{magicToken}`` - path segment is
**plural** ``approvals``.
1. Prefer the ``magicLink`` field this tool returns when present. MCP
synthesizes it from ``magicToken`` as
``{app}/approvals/{magicToken}`` when the backend sends only the token.
2. If only ``magicToken`` is present, build the URL solely as
``{app}/approvals/{magicToken}`` (plural). Do not use any other path.
3. While ``magicToken`` is null (processing or failed, or the caller lacks
campaigns edit plus the share feature): there is **no** shareable link.
Do not invent one.
4. **Forbidden** (all wrong; do not write these to ledgers or messages):
- ``/approval/`` singular (404; correct is ``/approvals/``)
- using the draft / campaign / campaign-test numeric ``id`` as the path
token (e.g. ``https://app.ken.so/approvals/658``)
- placeholders such as ``draft:658``, ``processing:draft-634``
- fabricating or guessing a magic token when create/get did not return one
5. Create never returns a client-ready link - only this get (or summary /
rotate) can supply a token. ``status=ready`` alone is not enough to
share for Batch / reverse-demo; still require the readiness gates below.
**Never treat ``status="ready"`` alone as usable.** Backend ``ready`` can
lag structured evidence during rollout, and Batch drafts must satisfy the
readiness counts below. For Batch (and reverse-demo) usable readiness,
require all of:
- ``progress.outcome == "ready"``
- when ``progress.qualification.required > 0``:
``progress.qualification.qualified >= 1`` and both
``progress.qualification.pending`` and ``progress.qualification.failed``
are zero
- when ``progress.segmentation.required > 0``: both
``progress.segmentation.pending`` and ``progress.segmentation.failed``
are zero (segmentation is a required-stage blocker alongside
qualification, personalization, and rewriting)
- when ``progress.personalization.required > 0``:
``progress.personalization.fullyPersonalized >= 1`` (one fully
personalized contact is sufficient) and
``progress.personalization.pending`` / ``failed`` / ``partial`` are all zero
- when ``progress.rewriting.required > 0``:
``progress.rewriting.pending`` / ``failed`` / ``partial`` are all zero
- no required stage may be pending / failed / partial
When the backend omits ``progress`` (legacy replica during mixed rollout),
status polling may still stop at ``ready`` or ``failed``. Batch and
reverse-demo usability is **UNVERIFIABLE** without ``progress``: do not
approve or launch from ``status`` alone. The caller must wait for a backend
replica that returns ``progress``, or route the draft to needs-review /
operator handling. Never treat a legacy ``ready`` response as a usable Batch
sample. Missing readiness fields remain absent - do not invent them.
Parameters
----------
campaign_test_id : int
The approval-test (draft) ``id`` returned by ``create_approval_test``
or a ``summary`` row.
Returns
-------
dict
``{ id, name, status, draftNumber, magicToken, magicLink, queueState,
queuePosition, queuedAt, buildStartedAt, submittedAt, feedbackSummary }``
plus additive readiness fields when the backend sends them:
``failureReason``, ``testCampaignId``, and ``progress``.
``queueState`` is nullable for legacy drafts and otherwise one of
``queued | building | processing | complete | failed``. ``status`` is
normally one of ``processing | ready | approved | notApproved | failed``;
any other value the backend may send is passed through unchanged rather
than raising. ``magicToken`` / ``magicLink`` are present only once a real
token exists (``null`` while processing or when none was issued);
``magicLink`` is the ready-to-copy client URL
(``{app}/approvals/{magicToken}``, plural path only - never singular
``/approval/``, never the draft id as the path segment). Prefer
``magicLink``; if only ``magicToken`` is set, construct only that plural
form. Never invent a token or a placeholder URL.
``feedbackSummary`` is ``{ approvedCount, changeCount, commentCount }``
(counts are ``null`` if the backend omits them).
``progress`` (when present) carries structured counts such as
``outcome``, ``reasonCode``, ``qualification.qualified``,
``segmentation.required`` / ``pending`` / ``failed``, and
``personalization.fullyPersonalized`` - preserve them exactly; do not
re-derive readiness from ``summary`` text. There is no scoring gate.
The public snapshot may include ``leadQualityScore`` (integer 1-10)
on a lead. Absent means that contact has no stored score.
queueState is the single source of truth for progress:
queued -> building -> processing -> complete | failed.
Under the Batch lane, "processing" can legitimately last hours - it
means AI work is coalescing, not hanging.
"failed" is not always terminal. ApprovalStatus has no NeedsReview
member, so a needs-review outcome surfaces as failed plus a
failureReason. ProviderUnavailable is retryable via repair; treating
every failed draft as dead discards recoverable work.
rotate_approval_link
Write.
Reissue a draft's magic token, invalidating the old share link. Use when an external approval link leaked or access must be revoked.
[API] Reissue a draft's magic token, invalidating the old share link.
Use this when an external approval link has leaked, or when you want to revoke
access to an already-shared draft. The previous link 404s immediately
afterward; share the new ``magicLink`` instead.
Share only the returned ``magicLink`` (or
``{app}/approvals/{magicToken}`` from this response's fresh token - plural
path only). Do not keep using the old link, do not invent a URL from the
draft id, and do not use singular ``/approval/``.
Parameters
----------
campaign_test_id : int
The approval-test (draft) ``id`` whose link to rotate.
Returns
-------
dict
``{ "magicToken", "magicLink" }`` - the fresh token and the ready-to-copy
client URL (``{app}/approvals/{magicToken}``, plural ``approvals`` only).
summary
Read.
Read external approval draft status and feedback counts for a campaign. Ops: summary (list drafts + counts). Call it first; read one draft's items with approval-tests-feedback for notApproved or ready drafts with counts.
[API] Read external approval draft status and feedback counts for a campaign.
Use this to answer "did the client approve the latest draft, and is there
autosaved feedback to review?" without loading full review snapshots.
ALWAYS call ``operation="summary"`` first. It returns one tiny row per
draft (no item bodies). Read one draft's feedback items with the approvals
operation ``approval-tests-feedback`` (``approval_test_id`` = the draft
``id``) for a draft whose ``status`` is ``"notApproved"``, or for a
``"ready"`` draft whose summary counts show autosaved feedback that the CSM
needs to review before client submission. A draft whose status is
``"approved"``, ``"processing"``, or ``"failed"`` has nothing to fetch (the
feedback endpoint returns an empty list for approved drafts), so skip it
and save the round trip and the context. Treat ``failed`` as terminal
rather than continuing to poll for ``ready``.
Operations
----------
summary (requires ``campaign_id``)
Lists the campaign's approval drafts. Returns, per draft, ONLY:
``{ id, name, status, draftNumber, createdDatetime, copyLinkEnabled,
magicToken, magicLink, queueState, queuePosition, queuedAt,
buildStartedAt, approvedCount, changeCount, commentCount }``.
Queue fields are omitted for legacy drafts; ``queueState`` is otherwise
``queued | building | processing | complete | failed``.
``magicLink`` is the ready-to-copy client link
(``{app}/approvals/{magicToken}``, plural path only); both it and
``magicToken`` are ``null`` until a real token exists (typically once the
draft is past processing; ``copyLinkEnabled`` is then ``true``), and stay
``null`` for a caller without campaigns edit plus the share feature. Never
invent a link from the draft ``id`` or a placeholder. The counts come
from each draft's ``feedbackSummary`` (frozen in the contract). If the
backend omits ``feedbackSummary`` the counts are ``null`` (NOT 0) and a
``countsUnknown: true`` flag is added so an unknown count is never
mistaken for "no requested changes" - a ``notApproved`` draft with
``null`` counts still needs an ``approval-tests-feedback`` drill-down.
``ready`` drafts can also have autosaved feedback before submission, so
nonzero counts on a ready draft are a valid reason to drill down. No
per-item bodies are returned here - inspect ``status`` and the counts to
decide which draft (if any) needs an ``approval-tests-feedback``
drill-down.
Parameters
----------
operation : "summary"
Which read to perform.
campaign_id : int, optional
Required for ``summary``. The campaign whose drafts you want to list.
Returns
-------
dict
For ``summary``: ``{ "drafts": [...] }``.
Examples
--------
Triage a campaign's drafts:
>>> await approval_feedback(operation="summary", campaign_id=123)