Billing billing
The workspace's plan, credits, usage and spend limits. Its plan usage (enrichment, emails) between two dates: usage-get with from_time and to_time. AI cost is db ai_spend. It reads only the caller's own workspace.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through billing_read and changes through billing_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: credit-estimates-create, workflow-spend-limits-delete, credit-rate-card-get, credit-savings-get, credit-spend-get, credits-get, spend-limits-get, subscription-get, usage-get, workflow-spend-limits-get, credit-ledger-list, invoices-list, spend-limits-update, workflow-spend-limits-update, abuse_quota_usage, billing_subscription
credit-estimates-create
Read. POST https://api.ken.so/v1/credits/estimates
Body (json): accountCount integer, campaignId integer, depth string, items array, kind string, leadCount integer, opens integer, pages integer, personalization boolean, sequenceSteps integer, targetLeads integer
Estimate the credits a campaign, a campaign build, an infra purchase, researching target accounts, working a number of leads, or Google Maps places searches and opens need. Computes only; nothing is charged. kind is campaign, build, infra, accounts, leads, or places. Returns millicredits plus display text in credits and dollars.
POST /api/v1/credits/estimates. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Any member role; the white-label client role gets 403.
Nothing is charged or reserved.
Bodies (fields that do not belong to the kind are refused):
- kind="campaign": optional campaign_id (defaults for leads, steps and
personalization come from that campaign), target_leads (1..1,000,000;
required when there is no campaign or its contact limit is 0),
sequence_steps (1..50, default the campaign's, else 3),
personalization (default the campaign's, else true). One finished lead
is about 3 rows qualified + 1 valid email + 1 personalization = 1.45
credits. Pass target_leads to price a different count: without it the
backend uses the campaign's contact limit when it is below 1,000,000,
else the campaign's lead count (a campaign with neither answers 400
on targetLeads).
Instead of personalization, depth prices every lead at a campaign
depth from the rate card's depths (never send both): bulk (3 rows
qualified + 1 valid email, 1.15 credits, $0.023 a lead), personalized
(plus 1 personalization, 1.45 credits, $0.029) or multichannel (tier-1:
plus a second personalization for the LinkedIn note and company
research, 13.75 credits, $0.275). The response names the depth and
targetLeads it priced and gives totalAmount in US cents. With
campaign_id, leads that already have a Safe email (an imported list)
are not quoted an email find: the email_found line covers only
leadsNeedingEmailFind of the targetLeads, so a fully emailed
campaign has no email_found line.
- kind="build": no other fields. A typical campaign build, or 0 when the
free monthly build is left (it covers up to 500 credits of AI work).
- kind="infra": items, 1..50 entries of {"action", "quantity"
(1..1,000, default 1)}. action is ken_inbox_monthly, prewarmed_inbox,
azure_domain_monthly, smtp_domain_monthly, domain_registration or
linkedin_account_monthly. domain_registration needs registrarPriceUsd
(the name's registrar price from the domain search, 0 < x <= 1,000; the estimate prices the name in credits)
and takes an optional renewalPriceUsd (same bounds). Monthly items count
their first month upfront.
- kind="accounts": account_count (wire accountCount), required, 1..1,000.
Prices adding that many target accounts: an estimated 12 credits of
account research per account, metered per run (its AI work; its web
pages are charged as web_scrape), plus about 6
email_found per account (about 18 credits, $0.36, per account). Use
it before accounts(operation="bulk-create").
- kind="leads": lead_count (wire leadCount), required, 1..1,000,000.
Prices working that many leads (importing and enriching them): 3 rows
ai_qualification, 1 valid email_found (only when found) and 1
ai_personalization per lead, 1,450 millicredits (1.45 credits, $0.029) a
lead. Use it when no campaign exists yet; for a campaign use
kind="campaign".
- kind="places": pages and opens (wire pages, opens), at least one above
0; pages 0..1,000, opens 0..100,000. Prices Google Maps places
(DEV-1091): 1 credit per page of up to 200 places (also when served from
Kenso's store), and detail, reviews or photos opens free up to 500 a
workspace a UTC day, then 0.1 credits (100 millicredits) an open. The
estimate assumes none of today's free opens is used yet.
Response: totalMillicredits (needed now), monthlyRecurringMillicredits
(added to the monthly infra reservation), lines (action, units,
millicredits, description), availableMillicredits (available credits for
campaigns and builds, the whole balance for infra), sufficient, freeBuild
(build only), inboxDomainEligibleMillicredits (infra only: the credits that
may pay the inbox and domain lines; free and bonus credits cannot, so
sufficient is false when those lines cost more, even when
availableMillicredits covers the total). display (added by this tool): summary, lines, and
availability when sufficient is false. A campaign outside the workspace
is 404.
workflow-spend-limits-delete
Write. DELETE https://api.ken.so/v1/workflows/{workflowId}/spend-limit
Path: workflowId
Remove one workflow's own spend limits. It goes back to the workspace defaults. Returns 204.
DELETE /api/v1/workflows/{workflowId}/spend-limit. Internal. Sends
Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the workflows feature (404
when off). Requires Workflows edit and the `billing` permission (Admin
template). The row holds settings
only, so it is deleted for good; read the workflow's limits first if you
may want to restore them. Like an update, it wakes the work the workflow
holds at a limit, which then runs against the workspace defaults. Afterwards workflow-spend-limits-get returns the
workspace defaults with isDefault true. A workflow id the workspace does
not have, or a deleted workflow, is 404 not_found.
credit-rate-card-get
Read. GET https://api.ken.so/v1/credits/rate-card
Get the credit rate card: the price of every credit action. Each item has millicreditsPerUnit plus display in credits and dollars.
GET /api/v1/credits/rate-card. Public. Sends Ken-Version 1.1. Static, so
it needs no workspace (X-Ken-Workspace-Id is sent only when one is given
or pinned). Any member role; the white-label client role gets 403.
Returns usdPerCredit ("0.02") and items: action, unit, unitSize (the
quantity the price is usually quoted for), millicreditsPerUnit (per ONE
unit), billing (per_use, monthly, one_time, yearly), pricing (fixed: the
exact price; typical: the work's price depends on what it does, and
millicreditsPerUnit is the median price of one unit across Kenso in the
last 30 days, 0 under 20 units), typical (typical rows: millicredits, null
under 20 units, windowDays, from, to), note (extra pricing
detail, omitted when empty), and display (added by this tool). The exact
price of typical work is on each ledger line.
| Action | Price |
|---|---|
| email_found | 1 credit ($0.02) per valid email found |
| ai_qualification | 50 credits per 1,000 rows ($1) |
| ai_personalization | 300 credits per 1,000 rows ($6), includes custom AI flows and AI variables |
| campaign_build (per build), reply_assist (per reply draft), autonomous_reply (per reply), ken_chat (per chat turn, the campaign builder's chat included), translation (per translation) | typical price (pricing typical) |
| studio_link | 1 credit ($0.02) per published Studio page |
| website_visitor_match | 49 credits ($0.98) per company matched from a website visit; a lookup with no match costs 0, and a match from Kenso visitor ID's own network data costs 0 |
| web_scrape | per page, listed only while Kenso offers it; free from Kenso's web archive, 0 credits with the workspace's own web scraping key |
| podcast_search | typical price per podcast request (a lookup makes one to a few), listed with web_scrape |
| extra_sends | 25 credits per 1,000 sends ($0.50) |
| ken_inbox_monthly | 200 credits ($4) per inbox per month |
| prewarmed_inbox | 300 credits ($6) per inbox, one time |
| azure_domain_monthly | 2,500 credits ($50) per domain per month |
| smtp_domain_monthly | 1,500 credits ($30) per domain per month |
| domain_registration | priced per domain name (the domain search shows it in credits), first year upfront |
| domain_renewal | priced per domain name, per year |
| linkedin_account_monthly | 1,500 credits ($30) per LinkedIn account per month |
One finished lead = 3 rows AI-qualified + 1 valid email found + 1 AI
personalization. The rate card has no item for it: about 3 rows are
qualified for every lead that passes, so never count 1 qualified row per
lead. Price it from the items: 3 x ai_qualification + 1 x email_found +
1 x ai_personalization, each at its millicreditsPerUnit. At today's rates
that is 3 x 50 + 1,000 + 300 = 1,450 millicredits = 1.45 credits ($0.029).
When the email comes from the workspace's own provider key or was
uploaded, email_found is free, so the lead is 450 millicredits = 0.45
credits ($0.009).
Free: emails found with the workspace's own provider key, uploaded
emails, segmentation and scoring (bundled with qualification), manual
sends from the inbox, contacts, workflows, seats, workspaces, your own
inboxes and domains, basic warmup, Kenso DB search, and verification of
uploaded lists (all behind rate limits). Paid plans include 200,000 sends
per billing month (extra_sends applies beyond that; on Free every send
costs credits) and 1 free campaign build per billing month (a very large
build can still cost credits past its free allowance).
credit-savings-get
Read. GET https://api.ken.so/v1/credits/savings
Query: from date, to date
Get Free with Ken: the work Ken did free for the workspace in a window, per item, valued at Clay's prices, plus the lifetime total.
GET /api/v1/credits/savings. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Any member role except Client; a Client seat and a
white-label client workspace get not_found. Read only.
from_date and to_date are inclusive UTC days (YYYY-MM-DD). to_date
defaults to today and from_date to the first of to_date's month; the
window is at most 366 days.
Response (under data): from, to, priceSource ("clay"), pricesCheckedOn
(when Clay's prices were last checked), totalUsdCents, items and lifetime
{since (first day recorded, omitted before any), totalUsdCents}. items are
always these six, in this order, then launch_offer when the launch offer
covered work in the window (email finds at the ken_db_email price,
enrichments at the enrichment_person price):
ken_db_email (emails from Kenso's database, $0.124 each on Clay),
email_verification (checks the email verifier answered and catch-all checks a paid
plan ran free, $0.054), enrichment_person (LeadMagic profile lookups a paid
plan ran free, $0.054), enrichment_company (LeadMagic company lookups,
$0.054), enrichment_tech_stack (LeadMagic technographics lookups, $0.144)
and website_page (pages served from Kenso's web archive, $0.054). People
Kenso Search added to a campaign (ken_search_person) are counted but left
out of items and totals while Clay's people search is free. Each item has
item, units, unitPriceUsdMicros (Clay's price of one unit in millionths of
a dollar; omitted for launch_offer when it mixes email finds and
enrichments) and valueUsdCents. totalUsdCents is the sum of the items, and
each item the sum of its daily rows: list them with
analytics_events(operation="credit-savings-rows-list").
An exempt workspace's savings are only its free work, never the cost it
was not charged.
credit-spend-get
Read. GET https://api.ken.so/v1/credits/spend
Query: period string
Get what the workspace spent per category (infrastructure, ai, data, sending, calling), per kind of work and per campaign, this billing month, the last 30 days or all time. Millicredits and USD cents plus display text.
GET /api/v1/credits/spend. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Needs the billing feature (Admin); other roles get
403. Read only.
period: billing_month (default), last_30_days, or all_time. On the Free
plan billing_month covers everything since the workspace signed up and
comes back as since_signup.
Response: period (billing_month, since_signup, last_30_days, all_time),
from (inclusive, omitted for all_time), to (exclusive), totalMillicredits,
totalAmount {amount (USD cents), currency}, categories (always the five:
infrastructure, ai, data, sending, calling, in that order; each has category,
millicredits, amount, lineCount), addedExpiredLineCount (grant, expiry
and adjustment lines in the period, never part of the spend).
actions: spend per kind of work, largest first, one row per credit action
with a line in the period (action, title such as "Valid email found",
category, millicredits, amount, lineCount); grants and expiries are left out.
campaigns: spend per campaign, largest first (campaignId, campaignName,
millicredits, amount, lineCount), at most 50 campaigns plus one row with
campaignId null for the work tied to no campaign; campaignsTruncated is true
when more campaigns had spend. campaignName is null for a deleted campaign.
Spend is net: a refund or overrun write-off counts against its charge's
category, action and campaign, so a row can be negative when a refund lands in a later
period than its charge. Lines on an exempt workspace (shadow) count in
lineCount but add no spend. A master or standalone workspace includes its
white-label children's lines; a child sees only its own.
List the lines behind a category with
billing(operation="credit-ledger-list", category="ai").
display (added by this tool): period, total, and one line per category.
credits-get
Read. GET https://api.ken.so/v1/credits
Get the workspace credit balance, what is reserved for sending and LinkedIn, and what is available for data and AI. Amounts in millicredits plus display text in credits and dollars (1 credit = $0.02).
GET /api/v1/credits. Public. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
Any member role (admin, member, view_only); the white-label client role
gets 403. A white-label child sees its master's pooled balance.
1 credit = 1,000 millicredits = $0.02. Fields (millicredits unless noted):
- balanceMillicredits: open grants minus debt.
- includedMillicredits: remaining plan-included credits (they expire at
includedExpiresAt, omitted when none are left).
- purchasedMillicredits: purchased, granted and other non-expiring credits.
- debtMillicredits: usage no grant has covered yet. The next grant or
purchase repays it first.
- reservedMonthlyMillicredits: monthly cost of the active Kenso inboxes,
domains and LinkedIn accounts, held back for infra. reservedItems lists
them by action (count, monthlyMillicredits, nextRenewalAt: when the next
of them renews, UTC; in the past while a charge for one of them is
unpaid, omitted while their first charge is still pending).
- availableMillicredits: what data and AI work may spend = balance -
reserved.
- monthlyIncludedCredits (whole credits): credits the plan grants each
billing month.
- usdPerCredit: "0.02".
- exempt: true for bypass and Premium (VIP) workspaces. Their usage is
written as shadow ledger lines and never charged. Dfy is a credit plan
(not exempt); the Kenso team allocates its credits.
- creditState: healthy, low, or out. low = under 500 credits available.
out = the workspace cannot start data and AI work (available credits at
or below 0, or a white-label child with nothing left of its cap): research,
email finding and AI work are paused, while sending and warmup keep
running. Exempt workspaces are always healthy. Check it before starting
credit-spending work; at out, tell the user to add credits (see below).
- exhaustedAt: when available credits last dropped to zero or below.
- grandfatheredUntil: until when a legacy plan keeps its grandfathered
allowance.
- sends: includedPerPeriod (omitted or null when sends are not metered, 0
when every send costs credits, as on Free), usedThisPeriod,
periodStart, periodEnd. Paid plans include 200,000 sends per billing
month; each send beyond that costs 25 credits per 1,000 ($0.50).
Manual sends from the inbox are free and do not count.
- builds: freeRemainingThisPeriod (paid plans get 1 free campaign build per
billing month, free up to 500 credits of AI work; work beyond that is
charged in credits) and overrunAvailable.
- autoTopUp: enabled, thresholdCredits, packCredits, lastError. Read only
here; it is changed in the Kenso app.
- launchOffer: startsAt, endsAt (endsAt is exclusive), used, limit,
stoppedAt, stoppedReason. Present on an active paid plan while the
window is open (Nov 10 to Nov 24, 2026 UTC): email finding and profile
enrichment cost no credits and run even at creditState out, up to limit
(100,000) lookups per workspace under the fair use policy, found or not.
used is the count so far. Once it reaches limit the offer stops for the
workspace: stoppedAt is set, stoppedReason is fair_use, and finding and
enrichment use credits again. Everything else is charged as usual.
display (added by this tool): balance, available, included, purchased,
debt, includedExpires, monthlyIncluded, reserved ("Sending + LinkedIn: X
credits/mo ($Y) reserved. Data / AI: the rest."), sends, builds, exempt,
launchOffer ("Launch offer: email finding and profile enrichment cost no
credits through <last day> (UTC), up to <limit> lookups under the fair use
policy (<used> used)." or, once stopped, "Launch offer ended: this
workspace passed the fair use limit of <limit> free lookups, so we stopped
the offer. Email finding and profile enrichment use credits again."),
creditState (only when low or out: "Low on credits: ..." or "Out of
credits: research, email finding and AI work are paused. Sending and
warmup keep running.").
Who adds credits depends on the plan: self-serve plans buy them in the Kenso
app (Settings, Billing); on Dfy the Kenso team adds them; a white-label
child's credits pool at its parent workspace.
spend-limits-get
Read. GET https://api.ken.so/v1/spend-limits
Get the workspace's workflow spend limits: the all-workflows monthly limit, the defaults a workflow without its own limits reads as, the at-limit action, and every workflow that has its own limits.
GET /api/v1/spend-limits. Internal. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the workflows feature on the workspace (404 when it is off) and the Workflows page (view); the Client template gets 403. Money is millicredits: 1 credit = 1,000 millicredits = $0.02. null means no limit. Fields: - workflowsMonthlyLimitMillicredits: monthly limit across every workflow (default 6,000,000 = 6,000 credits). - spentThisMonthMillicredits: what every workflow together spent this UTC calendar month (settled charges plus open credit holds), the amount the all-workflows limit counts. - defaults: monthlyLimitMillicredits (default 1,000,000), perRunLimitMillicredits (default 25,000) and runsPerDay (default 50), what a workflow without its own limits reads as. - atLimit: pause, ask or hold, what a workflow does at a limit (default pause). pause stops the run, ask waits for a person, hold keeps the run queued until a limit is raised. runsPerDay is the exception: a run over it waits until 00:00 UTC whatever atLimit says, and the workflow stays on. - isDefault: true when the workspace never set its limits. - workflows: workflow_spend_limit rows (see workflow-spend-limits-get) for the workflows that have their own limits, ordered by workflowId, each with its own spentThisMonthMillicredits and waitingRuns. - waitingRuns: runs of every workflow (with or without its own limits) waiting at a limit right now: paused, asking a person, or held by at_limit hold (those also try again every hour by themselves). - updatedAt: null while isDefault. display (added by this tool): each limit and spentThisMonth in credits and dollars, or "No limit", the at-limit action and waitingRuns in words.
subscription-get
Read. GET https://api.ken.so/v1/billing/subscription
Get the workspace subscription. Internal. Any authenticated member. purchasedExtraSeats includes 0. actualMonthlyAmount stays major units.
GET /api/v1/billing/subscription. Internal. Answers only when Ken-Version
is 1.1. Sends X-Ken-Workspace-Id. Any authenticated member. Returns the
subscription body. One resource, with no totalCount and no clientId.
planType, status, and interval are lowercase snake_case. planType platform
is the one self-serve plan (DEV-1544): 200,000 sends and 5,000 credits per
billing month. includedMonthlyCredits (credits granted per billing month)
and grandfatheredUntil (until when a legacy plan keeps its grandfathered
allowance, omitted otherwise) are additive. usage[].metric is a snake_case
meter name (campaigns, leads, emails, linked_in_seats, ai_credits). On
platform the emails meter is the 200,000 included sends and leads and
linked_in_seats are unlimited (limit -1). ai_credits is the legacy AI-credit
cap, not the credit balance: read credits with operation credits-get. That
meter is not an add-on checkout. purchasedExtraSeats is
the billing state's existing purchased-seat count and is present including
0 when none have been bought. actualMonthlyAmount stays the existing
major-unit amount (for example 49.5) and is not rescaled.
sendingInfrastructure.status is not_required, ready, or pending.
cancelAtPeriodEnd, cancelEffectiveAt (omitted unless a cancel is set),
pause {startsAt, resumesAt, months} (omitted unless a pause is set or
running), canceledAt (omitted unless the last paid plan ended), canCancel
and canPause are additive (DEV-5981). Legacy billing_subscription,
billing_usage_ledger and the admin_billing operations stay. Staff billing
tools stay staff.
usage-get
Read. GET https://api.ken.so/v1/usage
Query: campaignId integer, from date-time, groupBy string, includeLedger boolean, to date-time
Return workspace usage for a reporting window. Internal. cost is Kenso's provider cost in USD cents, not the workspace price. group_by is day, campaign, or service.
GET /api/v1/usage. Internal. Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. Requires the `billing` permission. from_time and to_time are sent as from and to. cost.amount is an integer number of USD cents and cost.currency is usd. cost is Kenso's provider cost for this workspace in USD cents. It is not what the workspace pays. What the workspace pays is in credits: billing operations credits-get and credit-ledger-list. include_ledger adds the first 50 billing ledger rows. Optional campaign_id must belong to the workspace.
workflow-spend-limits-get
Read. GET https://api.ken.so/v1/workflows/{workflowId}/spend-limit
Path: workflowId
Get one workflow's effective spend limits. A workflow without its own limits reads as the workspace defaults with isDefault true.
GET /api/v1/workflows/{workflowId}/spend-limit. Internal. Sends
Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the workflows feature (404
when off) and the Workflows page (view); the Client template gets 403.
Millicredits: 1 credit = 1,000 millicredits. null means no limit. Fields:
monthlyLimitMillicredits, perRunLimitMillicredits, runsPerDay,
alertPercent (50, 80 or 90: the share of the monthly limit that sends a
spend alert; null for none; 80 while isDefault), atLimit (pause, ask or
hold; a run over runsPerDay waits until 00:00 UTC whatever it says), steps (per-step limits: nodeId plus perRunLimitMillicredits and/or
monthlyLimitMillicredits), isDefault, updatedAt (null while isDefault),
spentThisMonthMillicredits (what the workflow spent this UTC calendar
month: settled charges plus open credit holds, the amount its monthly
limit counts), waitingRuns (its runs waiting at a limit right now: paused,
asking a person, or held by at_limit hold, which also try again every hour
by themselves). These are the limits the workflow runs
with: a published definition's limits only fill them in the first time,
for a workflow that has none. A workflow's own limits replace the
workspace defaults as a whole: a limit it leaves null is no limit, not the
default. A workflow id the workspace does not have, or a deleted workflow,
is 404 not_found.
display (added by this tool): each limit and spentThisMonth in credits and
dollars, or "No limit", the at-limit action and waitingRuns in words.
credit-ledger-list
Read. GET https://api.ken.so/v1/credits/ledger
Query: accountId integer, action string, actorUserId integer, campaignId integer, category string, chatId integer, contactId integer, cursor string, from date-time, limit integer, listId integer, q string, runId string, to date-time, trigger string, workflowId integer
List the workspace credit ledger, newest first. Each line has millicredits, its category, plus display in credits and dollars. Filters: from_time, to_time, action, campaign_id, category, trigger, actor_user_id, list_id, account_id, workflow_id, chat_id, contact_id, run_id, q (what did this contact, list, chat or run cost).
GET /api/v1/credits/ledger. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Any member role; the white-label client role gets 403.
Cursor list: limit (1..200, default 50) and cursor; read
pagination.hasMore and pagination.nextCursor. Optional filters:
from_time and to_time (ISO-8601 instants, inclusive, sent as from and to),
action (credit actions, comma-separated, any matches, such as email_found, ai_qualification,
ai_personalization, campaign_build, reply_assist, autonomous_reply,
extra_sends, ken_inbox_monthly, prewarmed_inbox, azure_domain_monthly,
smtp_domain_monthly, domain_registration, domain_renewal,
linkedin_account_monthly, studio_link, studio_build, account_research,
committee_mapping, account_writer, account_plan, ken_chat (the campaign builder's chat
included), translation, the workflow_* actions such as
workflow_ai_qualify, meeting_notes, meeting_brief, web_scrape, phone_found,
call_brief, website_visitor_match, linkedin_voice_note,
imported_meeting_notes, grant, expiry,
overrun_write_off, manual_adjustment, refund), campaign_id, category
(comma-separated, any of them matches: infrastructure, ai, data,
sending, added_expired; the Billing page's chips). DEV-10792, all ANDed:
trigger (comma-separated: person, ken, workflow, campaign_schedule,
renewal), actor_user_id (lines a member started), contact_id and
account_id (the line's subject), list_id and workflow_id (the line's list
or workflow, or its subject), chat_id (a Ken chat's lines and its Ken run;
an unknown chat gives an empty page), run_id (every line of one run, 1-100
chars), q (2-200 chars, case-insensitive: description, title, webUrl, or
the name of the line's contact, account, list, workflow, chat or campaign).
Items: id (number), createdAt, action, units (omitted for token-priced
and bookkeeping lines), millicredits (signed), reason (charge, release,
settle, add_on, rebaseline, write_off, expire, launch_offer for a find the
launch offer made free, email_pool_hit for emails Kenso's shared pool gave
for free: always shadow at 0 millicredits, units counts the emails,
own_key for work that ran on the workspace's own provider key: always
shadow at 0 millicredits, units counts what it delivered),
campaignId, workspaceId
(the workspace that caused the line), description, shadow, category, and
display (credits and dollars, added by this tool).
What the line was for (DEV-10792; omitted on older lines and when it does
not apply): title (plain name of the work, always set), subjectType
(contact, account, list, workflow, chat, campaign), subjectId,
subjectName, webUrl, webSite and webPage (a web read's page), trigger
(person, ken, workflow, campaign_schedule, renewal), actorUserId,
actorName, workflowId, workflowName, listId, listName, campaignName,
chatId, chatTitle, chatMessageCount, run {id, kind, title, lineCount,
millicredits, startedAt} (the run the line belongs to, with its total
on every page), paidFrom (paid, free or mixed credits), creditGrantId
and creditGrantKind (paid or free). Names are the line's own
workspace's and are omitted once the object is gone.
category: infrastructure (inboxes, domains, LinkedIn accounts), ai,
data (emails found, web pages, workflow data steps), sending (extra
sends), calling (call minutes, call recordings and phone numbers), or
added_expired (grants, expiries, manual adjustments). A
refund or overrun write-off is in the category of the charge it
corrects (ai when that charge is not found). Treat an unknown value as
a new category.
Sign convention: charges are positive, grants are positive (reason
add_on), refunds, write-offs and expiries are negative. shadow is true on
an exempt workspace: the cost was recorded but not charged. One line per
batch (a job pass per campaign, a build step report, a renewal run). A
master or standalone workspace also sees its white-label children's lines;
a child sees only its own.
invoices-list
Read. GET https://api.ken.so/v1/billing/invoices
Query: limit integer
List the workspace invoices, newest first. Internal. Workspace admins. Subscription, credit pack, top-up and domain invoices with PDF and hosted links. limit 1..100, default 20.
GET /api/v1/billing/invoices. Internal. Answers only when Ken-Version is
1.1. Sends X-Ken-Workspace-Id. Requires the billing feature (workspace
admins). limit is 1..100 (default 20). There is no cursor:
pagination.hasMore says whether older rows exist (DEV-1784).
Each row: id, object "invoice", kind (subscription, credit_pack,
credit_top_up, domain or other), createdAt, description (for example
"Platform · monthly" or "Credit pack · 5,000 credits"), amount ({amount,
currency}, minor units), status (paid, open, uncollectible or void),
billingEmail, pdfUrl, hostedUrl. Draft invoices are left out. A payment
made in Checkout (a credit pack, a domain order, or extra leads as kind
other) is its Checkout session (cs_...): status paid, the charge receipt as
hostedUrl and no pdfUrl. A workspace without a Stripe customer, or a
white-label child (its parent is billed), gets an empty list. 503
service_unavailable when Stripe cannot be read.
spend-limits-update
Write. PATCH https://api.ken.so/v1/spend-limits
Body (json): atLimit string, defaults object, workflowsMonthlyLimitMillicredits integer
Change the workspace's workflow spend limits. Only the fields you send change. A null limit clears it (no limit). Amounts are millicredits (1 credit = 1,000).
PATCH /api/v1/spend-limits. Internal. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the workflows feature (404 when off). Requires Workflows edit and the `billing` permission (Admin template). Takes effect at once, also for runs that are held at a limit: every saved change wakes the work every workflow holds at a limit. A workflow a limit paused goes back on, and runs waiting at a limit try their step again now; work still over the new limits waits again. changes (snake_case or camelCase keys; at least one): - workflows_monthly_limit_millicredits: 0..100,000,000,000, or null for no limit across all workflows. - defaults: an object with monthly_limit_millicredits and per_run_limit_millicredits (0..100,000,000,000, or null for none) and runs_per_day (1..100,000, or null). Only the keys you send change. These are what a workflow without its own limits reads as; a workflow that has its own limits keeps them (they replace the defaults). - at_limit: pause, ask or hold. Cannot be null. The first write creates the workspace's limits; fields you did not send keep their default values. Returns the full spend_limits object (see spend-limits-get) with display added.
workflow-spend-limits-update
Write. PATCH https://api.ken.so/v1/workflows/{workflowId}/spend-limit
Path: workflowId
Body (json): alertPercent integer, atLimit string, monthlyLimitMillicredits integer, perRunLimitMillicredits integer, runsPerDay integer, steps array
Set one workflow's own spend limits. Only the fields you send change. A null limit clears it (no limit). Amounts are millicredits (1 credit = 1,000). A workflow's own limits replace the workspace defaults.
PATCH /api/v1/workflows/{workflowId}/spend-limit. Internal. Sends
Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the workflows feature (404
when off). Requires Workflows edit and the `billing` permission (Admin
template). Takes effect at once: a saved change wakes the work the
workflow holds at a limit. If a limit paused it, it goes back on, and its
runs waiting at a limit try their step again now; work still over the new
limits waits again. A workflow id the workspace does not have, or a
deleted workflow, is 404 not_found and nothing is saved.
changes (snake_case or camelCase keys; at least one):
- monthly_limit_millicredits, per_run_limit_millicredits:
0..100,000,000,000, or null for no limit.
- runs_per_day: 1..100,000, or null for no limit.
- alert_percent: 50, 80 or 90 (spend alert at that share of the monthly
limit), or null for no alert.
- at_limit: pause, ask or hold. Cannot be null.
- steps: a list of at most 200 {node_id, per_run_limit_millicredits,
monthly_limit_millicredits}. node_id is 1-64 characters of letters,
digits, _ and -, unique in the list; each step needs at least one limit.
Sending steps replaces the whole step list; null or [] clears it.
The first write creates the workflow's row. Fields you did not send keep
the workspace default values at that moment. A limit you leave null is no
limit, not the workspace default. Returns the workflow_spend_limit object
(see workflow-spend-limits-get) with display added. Undo all of a
workflow's own limits with workflow-spend-limits-delete.
abuse_quota_usage
Read.
Get live abuse/overload quota usage for one client. Requires client_id.
This read model is separate from billable Campaigns/Leads/Emails usage. It reports the minute/day/month windows used to stop runaway API, export, campaign, AI, enrichment, and Search loops. Requires client_id; the backend verifies workspace membership.
billing_subscription
Read.
Get a client's billing subscription, usage meters, and sending readiness. Requires client_id. Available to client-facing principals (read-only, D5).
[API] Get a client's billing subscription, usage meters, and sending
infrastructure readiness.
Client-facing (task 15 / D5): this read is allow-listed so agents can preflight
plan/usage. The admin_billing operations and billing_usage_ledger stay blocked.
Parameters:
-----------
client_id : int
The client (workspace) whose subscription to load. Required. The backend
scopes billing to this client and verifies the caller is a member of it
(or a super admin); otherwise it returns 403. There is no JWT client-id
claim, so this must be supplied explicitly.
The backend response includes:
- planType/status/interval/currentPeriodStart/currentPeriodEnd. planType
Platform is the one self-serve plan (DEV-1544): $200/mo, $540 per
quarter or $1,920 per year, with 200,000 sends and 5,000 credits per
billing month. Free, Dfy, Premium (VIP) and the grandfathered
Starter/Growth/Core plans stay readable.
- includedMonthlyCredits (credits the plan grants each billing month, 0
when it grants none) and grandfatheredUntil (until when a legacy plan
keeps its grandfathered allowance, null otherwise). Additive (DEV-1544).
Read the credit balance with the billing tool, operation credits-get
(1 credit = $0.02).
- usage[] with Campaigns/Leads/Emails meters (plus a LinkedInSeats meter when
the plan tracks seats). On Platform the Emails meter is the 200,000
included sends per billing month, and Leads and LinkedInSeats are
unlimited (limit -1). An AiCredits meter is the legacy AI-credit cap,
not the credit balance.
The Leads meter counts contacts: qualified profiles with a safe email.
It resets every month on the billing anchor (currentPeriodStart's day),
including inside a quarterly invoice. Importing profiles does not move
this meter. The contact allowance applies to Free and Premium (VIP)
workspaces; Platform, Dfy and the grandfathered plans have unlimited
contacts. PROFILE_CAP_REACHED means this import would put the campaign
over 10 times its contact limit in profiles. Retry with the remaining
number in the error, or fewer. LEAD_CREDITS_LIMIT_REACHED means the paid
contact target exceeds current ready contacts plus the remaining contact
allowance. Processing stops separately when the monthly contact
allowance is spent. An import of profiles does not spend the contact
allowance.
- kenMailboxSlots: { used, limit } used is the Kenso-provisioned inbox
count. limit is a display figure (Core/Premium 40 plus
purchasedExtraEmailBlocks * 20, 0 on grandfathered plans). It does not
gate buy or import: size carts from remaining daily send (domain
capacity), never from slots. On credit plans each Kenso inbox costs 200
credits ($4) per month. On a white-label child, limit is its
mailbox cap, but limit - used is not its headroom: used excludes
connected inboxes. Compare caps.mailboxes to the full inbox count.
- managedByWorkspace { id, name } and caps { emails, leads, aiCredits,
domains, mailboxes }: white-label child only. caps.domains and
caps.mailboxes are stock caps over every domain and inbox in the
workspace, connected ones included. Buy, import, and connect stop there.
- purchasedExtraLeadBlocks, purchasedExtraEmailBlocks (legacy Core/Premium extras)
- isPublicPlan: true when the plan is in the public catalog (Platform)
- linkedInSeatBillingEnforced (bool): true when the plan has a metered, non-
unlimited LinkedInSeats entitlement, so LinkedIn seat connects are gated by
the seat limit (see linkedin(operation="create-connect-session"))
- sendingInfrastructure.status: NotRequired, Ready, or Pending
- sendingInfrastructure target/assigned daily sends and domain counts
Pending means Kenso is provisioning or buying domains; the customer does not
need to take action from this tool.
Example data (Platform monthly):
{
"planType": "Platform",
"status": "Active",
"interval": "Monthly",
"isPublicPlan": true,
"includedMonthlyCredits": 5000,
"grandfatheredUntil": null,
"usage": [{"metric": "Emails", "used": 12345, "limit": 200000}],
"sendingInfrastructure": {
"status": "Pending",
"targetDailySends": 1000,
"assignedDailySends": 500,
"requiredDomainCount": 5,
"assignedDomainCount": 3,
"pendingReason": "Pending inventory",
"availableUntil": null
}
}