Billing
An organization's subscription, plan, usage and limits.
Get the organization's billing
Organization owners and admins. The subscription (members × price + extra workspaces × price), the trial, media storage per workspace and recent invoices.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
access- What the organization may do now;
noneis read-only.One offull,grace,none accessReason- Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntiladAccounts- used (ad accounts connected across the organization's workspaces, each once, on its busiest platform) and cap (Pro and the trial: 3 per platform; null: no cap). The cap counts per platform: an account new to the organization beyond its platform's cap isn't added by the sync: GET /integrations/{platform} shows it in
adAccountLimit; accounts already connected always stay. adAccountsByPlatform- Connected ad accounts per platform, each once across the organization's workspaces (
{"meta": 2}): only platforms with at least one. billingUrl- The billing page in the app.
catalogue- The plan catalog, the one source of every price, cap and gate (the pricing page): version, currency, yearlyDiscountPercent (20), credits {usdPerCredit, minimumPurchase, rolloverMonths, trialCredits}, trial {days, workspaces, credits}, recommendation {businessBesideProUsdCents, enterpriseFromBusinessYearlyMonthlyUsdCents}, plans [{key, name, productName, unitLabel, description, terms (the plan's terms as strings, snake_case: workspaces, max_members, max_guests, max_ad_accounts, storage_gb, storage_gb_per_extra_workspace, included_usage, included_members, included_workspaces, features, support, …), items [{key, name, product, monthlyUsdCents, yearlyUsdCents, includedQuantity}], storagePrice (null on Pro, or {lookupKey, unitAmountDecimal, perGbMonth, usdPer100GbMonth})}] and enterprise {fromMonthlyUsdCents, includedMembers, includedWorkspaces, creditsBase, creditsPerExtraMember, storageGbDefault, storageGbPerExtraWorkspace, usdPer100GbMonth, slaPercent, support}.
configured- Billing is set up for this deployment.
contactUrl- The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
credits- AI in credits (1 credit = $0.01; whole numbers). Every credit, included, added by Pluto or bought, is valid 12 months unless Pluto set another expiry; unused credits roll over and are used in one order (included, then added by Pluto, then bought; the soonest to expire first within each), only while the plan is active. included (this month's; the trial: 300 in total), used (this month), remaining (usable now), rolledOver (left of earlier months' included credits), bought (left of bought credits), goodwill (left of credits Pluto added), available (used + remaining), perMember (1,200 on Pro, 1,500 on Business; null otherwise), periodStart, nextCreditsAt (next month's included credits; null without a plan), nextExpiry {credits, expiresAt}, alert (
none,almostat 80%,reachedat 100% ofavailable), creditPrice (0.01), value {included, used, remaining} (USD), sources {contract, addedMembers} (Enterprise: the contract's credits a month and 2,000 for each member added during it; null otherwise), lots [{id, source (included,goodwill,purchase,auto_top_up), credits, remaining, addedAt, expiresAt}] in the order they're used, canBuy, buyBlocked (choose_plan: the trial or no plan;complimentary: complimentary access without a card on file), autoTopUp (see PUT …/billing/credits/auto-top-up; null without a plan) and waiting (AI waits for credits now). enforced- Paid access is enforced for this organization.
enterprise- An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (
monthly; an older contract may beyearlyorquarterly), monthlyPrice (one price a month for the whole contract, with the additions paid so far, whole dollars), invoiceAmount (one regular invoice), nextInvoiceAt, nextInvoiceAmount (what that invoice bills, with the additions paid before it)}, members and workspaces {contracted (with paid additions), used, pending (in unpaid additions)}, prices {member, workspace} a month each added during the contract, creativeMemory {included}, autoTopUp {enabled, credits, monthlyCap, usedThisMonth, version}, notices [{metric, threshold, message}]. Beyond the contract a new member or workspace answers402 plan_limitwithreason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions. guests- Guests now: free.
hasCustomer- A Stripe customer exists (the portal opens).
includedUsage- Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoices- Recent invoices.
limits- What the plan (or the trial, or complimentary access) includes: plan, name, workspaces (null: unlimited), maxMembers, maxGuests and maxAdAccounts (Pro and the trial: 5, 10 and 3 ad accounts per platform, per organization; null: unlimited), storageGb (Enterprise: the contract's), storageGbPerExtraWorkspace (Pro 50 up to its 3 workspaces, Business 100, Enterprise 200), includedUsagePerMember, includedMembers, includedWorkspaces, features (
workspace_limits,usage_breakdown,audit_log,workspace_access,extra_storageon Business and Enterprise;sso_scim,invoicing,sla,creative_memoryon Enterprise), support. members- Members now: paid.
nextInvoice- amount, currency, date.
organization- id, name, workspaces [{id, name}], enterprise.
plan- key (
pro,business,enterprise) and name while subscribed; null during the free trial and without a plan. plans- Pro, Business and Enterprise with this organization's numbers.
rates- currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnly- since: read-only since then, until the organization subscribes; nothing is deleted.
recommendation- What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (
proorbusiness, the oneplans[].recommendedmarks, the same at both), businessBesidePro (Pro is recommended and Business costs at most $50 a month more at that period: show it beside Pro), enterpriseSuggested (Business billed yearly costs $500 a month or more: sales is worth a call)}. salesUrl- Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
source- Where access comes from.One of
subscription,trial,complimentary,none status- The Stripe subscription's status.One of
none,trialing,active,past_due,unpaid,canceled,incomplete,incomplete_expired,paused storage- includedGb, includedBytes, usedGb, usedBytes, workspaces [{workspaceId, name, usedGb, usedBytes}], extra {available (Business and Enterprise with a subscription; Pro's storage is fixed), enabled, limit (null: no limit), version, pricePerGbMonth, maxExtraGb, maxExtraBytes (null: no limit), extraGb, extraBytes, costSoFar}. Each GB field is rounded to 2 decimals and each Bytes field is exact (1 GB = 1,073,741,824 bytes, as storage is metered).
subscription- plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
support- The support the organization has now:
email(Email) on the trial and Pro,priority_email(Priority email) on Business,shared_channel(a channel shared with the team) on Enterprise.One ofemail,priority_email,shared_channel syncedAttrial- startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailable- Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspaces- used (active workspaces), cap (the hard limit: the trial 1, Pro 3; null: no cap), included (what the plan's price covers; Enterprise: the contracted workspaces), price (what the next workspace beyond
includedadds: amount, currency, interval; null without one and on Enterprise) and tiers (a graduated workspace price's tiers: from, to, amount, billed; null for a flat price, as on Pro and Business).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing" \
-H "Authorization: Bearer $PLUTO_KEY"Start subscribing
Returns the Stripe Checkout URL where a person subscribes the organization for its members and extra workspaces. A yearly plan says first what it bills today for the year. Nothing is charged until they complete it. 409 when it already subscribes, or doesn't fit the plan (Pro: up to 5 members, 10 guests, 3 workspaces, 3 ad accounts per platform and its media storage; reason too_many_members, too_many_guests, too_many_workspaces, too_many_ad_accounts or too_much_storage, with upgradeTo).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
cadence- Billing period; yearly is 20% off, billed for the year up front.One of
monthly,yearly plan- Pro (up to 5 members, 10 guests and 3 workspaces), or Business (5 members and 10 workspaces included, more of each at any time). Enterprise is through sales.One of
pro,business
Response
url- Where the person completes it.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The organization already subscribes, or doesn't fit the plan.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/checkout" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2cfcfc9a-3517-40d8-bfa8-4b2dbe3b07bf" \
-H "Content-Type: application/json" \
-d '{
"cadence": "monthly",
"plan": "pro"
}'List credit purchases
Purchases and auto top-ups (never the monthly grants), newest first.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
purchases- Newest first.
purchases[].amount- Its price: $0.01 a credit.
purchases[].createdAt- RFC 3339.
purchases[].credits- Credits bought.
purchases[].currencyusd.purchases[].expiresAt- 12 months after it became usable.
purchases[].id- The purchase.
purchases[].invoice- id, number, status, hostedInvoiceUrl.
purchases[].paidAt- When it was paid.
purchases[].problempayment_failed: the card was declined (pay the invoice or update the card);no_payment_method: an auto top-up found no card.One ofpayment_failed,no_payment_methodpurchases[].remaining- Credits left on it.
purchases[].source- Bought by an admin, or by auto top-up.One of
purchase,auto_top_up purchases[].status- Usable once paid.One of
pending_payment,paid,void
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/credits" \
-H "Authorization: Bearer $PLUTO_KEY"Buy credits
Buys credits at $0.01 each, any whole number from 1,000 ($10), on every plan. They're charged at once to the card on file (a one-off invoice) and usable once it's paid, for 12 months, after the included credits, oldest first; never sold on credit. 409 with reason: choose_plan during the trial or without a plan, reason: complimentary on complimentary access without a card on file (with contactUrl). Only a signed-in person buys credits: agents and API keys get 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
credits- Any whole number from 1,000 to 10,000,000.
Response
amount- Its price: $0.01 a credit.
createdAt- RFC 3339.
credits- Credits bought.
currencyusd.expiresAt- 12 months after it became usable.
id- The purchase.
invoice- id, number, status, hostedInvoiceUrl.
paidAt- When it was paid.
problempayment_failed: the card was declined (pay the invoice or update the card);no_payment_method: an auto top-up found no card.One ofpayment_failed,no_payment_methodremaining- Credits left on it.
source- Bought by an admin, or by auto top-up.One of
purchase,auto_top_up status- Usable once paid.One of
pending_payment,paid,void
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409
choose_planorcomplimentary: credits can't be bought now. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/credits" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 214acac6-a7fb-4c83-a307-e9845c0c0c9c" \
-H "Content-Type: application/json" \
-d '{
"credits": 3
}'Set auto top-up
Off until an owner or admin turns it on. When the organization's credits run out, auto top-up charges the card on file for credits (a one-off invoice paid at once); they're usable once it's paid, and AI waits meanwhile. Never more than one top-up charge at a time, and never past monthlyCap in a calendar month (UTC) when one is set. A declined charge stays open (inFlight.problem: payment_failed) until it's paid or the card is updated. 409 with reason: choose_plan or complimentary (see POST …/billing/credits); a stale version is a 409. Only a signed-in person turns it on or changes it while it's on: agents and API keys get 403; turning it off always works.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
credits- Credits a top-up buys: any whole number from 1,000.
enabled- On or off.
monthlyCap- USD of top-ups per calendar month, whole dollars, such as
1000.00; null removes the cap; absent keeps it. version- The setting's
version(0 before the first change).
Response
credits- Credits a top-up buys.
enabled- On or off (off by default).
inFlight- The top-up being charged (at most one): id, credits, amount, createdAt, problem (
payment_failedor null), invoice. monthlyCap- USD of top-ups per calendar month; null: no cap.
usedThisMonth- USD topped up this month.
version- Pass it back when changing it.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/credits/auto-top-up" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 0668215c-8beb-4d3f-a490-f28b1894df93" \
-H "Content-Type: application/json" \
-d '{
"credits": 3,
"enabled": true,
"monthlyCap": "25.00",
"version": 3
}'Get billing details
The business name and billing email on invoices, the billing address (it decides the tax location), tax IDs with Stripe's verification status, and the tax exemption.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
address- line1, line2, city, postalCode, state, country.
email- Receives invoices and receipts.
name- The business name on invoices.
paymentTermscard: charged automatically;net_30: invoices are sent and due in 30 days (Enterprise).One ofcard,net_30poNumber- Enterprise: the purchase order number printed on every invoice.
taxExempt- Stripe's tax exemption.One of
none,exempt,reverse taxIds- Tax IDs.
taxStatus- Whether tax can be calculated from the address (
address_needed: add or complete it).One ofready,address_needed,not_collecting
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/details" \
-H "Authorization: Bearer $PLUTO_KEY"Update billing details
Changes appear on the next invoices. An address needs a two-letter country; a US address its state and ZIP code. poNumber is for Enterprise (422 otherwise).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
address- line1, line2, city, postalCode, state, country (two letters).
email- Receives invoices and receipts.
name- The organization's legal or billing name on invoices (a business, not a person).
poNumber- Enterprise: a purchase order number (1–40 characters) printed on every invoice; null removes it.
Response
address- line1, line2, city, postalCode, state, country.
email- Receives invoices and receipts.
name- The business name on invoices.
paymentTermscard: charged automatically;net_30: invoices are sent and due in 30 days (Enterprise).One ofcard,net_30poNumber- Enterprise: the purchase order number printed on every invoice.
taxExempt- Stripe's tax exemption.One of
none,exempt,reverse taxIds- Tax IDs.
taxStatus- Whether tax can be calculated from the address (
address_needed: add or complete it).One ofready,address_needed,not_collecting
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/details" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {},
"email": "maya@brevanne.com",
"name": "Brevanne",
"poNumber": "PO-2026-0917"
}'List additions
Enterprise: every addition, newest first, with its invoice.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
additions- Newest first.
additions[].createdAt- RFC 3339.
additions[].currencyusd.additions[].id- The addition.
additions[].invoice- id, number, status, hostedInvoiceUrl (where it's paid).
additions[].members- Members added.
additions[].nextInvoiceAt- From this invoice on it's part of every invoice.
additions[].paidAt- When the invoice was paid.
additions[].status- Active only once the invoice is paid.One of
pending_payment,active,void additions[].total- Invoiced, before tax.
additions[].workspaces- Workspaces added.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/enterprise/additions" \
-H "Authorization: Bearer $PLUTO_KEY"Add to the contract
Enterprise: adds members and workspaces at the quote's price and issues its invoice at once, due in 30 days like the contract (the hosted invoice page is the payment link). They're active once the invoice is paid (status: active); from the next invoice they're part of the monthly price. Nothing is removed before renewal; Creative Memory changes go through sales. 409 with reason: price_changed (and total) when expectedTotal differs from the price now. Only a signed-in person adds to the contract: agents and API keys get 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedTotal- The quote's total the admin agreed to.
members- Members to add (0 or more).
workspaces- Workspaces to add (0 or more).
Response
createdAt- RFC 3339.
currencyusd.id- The addition.
invoice- id, number, status, hostedInvoiceUrl (where it's paid).
members- Members added.
nextInvoiceAt- From this invoice on it's part of every invoice.
paidAt- When the invoice was paid.
status- Active only once the invoice is paid.One of
pending_payment,active,void total- Invoiced, before tax.
workspaces- Workspaces added.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409No running contract, or the price changed.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/enterprise/additions" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 3c81387e-86e1-468c-94e3-efeddab2f6f6" \
-H "Content-Type: application/json" \
-d '{
"expectedTotal": "150.00",
"members": 12,
"workspaces": 12
}'Quote an addition
Enterprise: what adding members and workspaces costs: $50 a member and $40 a workspace a month, paid now for the days left until the next invoice (today counts), then part of every invoice from the next one. Each added member brings 2,000 AI credits a month and each workspace 200 GB of storage. 409 without a running contract.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
members- Members to add (0 or more).
workspaces- Workspaces to add (0 or more).
Response
creditsPerMonth- AI credits a month the added members bring (2,000 each).
currencyusd.daysLeft- Days left until the next invoice, today included.
lines- Members, then workspaces. The amounts add up to the total.
monthlyIncrease- What every invoice's month grows by from the next invoice, before tax.
nextInvoiceAt- The next invoice: from it on the addition is part of every invoice (RFC 3339).
periodDays- Days in the invoice period.
periodStartsAt- When the invoice period it's charged for started (RFC 3339).
storageGb- Storage the added workspaces bring, GB (200 each).
total- Due now, before tax.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409No running contract.
- 422No members or workspaces to add, or too many.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/enterprise/additions/quote" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"members": 12,
"workspaces": 12
}'Change plan
A change that charges now (Pro to Business, monthly to yearly) needs the previewId of its preview (POST …/billing/plan/preview) from the same person: it is applied in one update at the previewed proration date, so Stripe charges the previewed amount, and refused, with nothing charged, when the preview is missing or not yours (422 on previewId), expired or already used (409, reason: plan_preview_expired), or the amount moved since (409, reason: plan_preview_changed). A declined card leaves the plan as it was (409, reason: payment_declined). Only a signed-in person confirms a charge: agents and API keys get 403. Pro to Business applies now, prorated and invoiced at once. Business to Pro applies at the end of the period when the organization fits Pro: up to 5 members, 10 guests, 3 active workspaces and 3 connected ad accounts per platform, and no more media than Pro includes for them (409 with reason too_many_members, too_many_guests, too_many_workspaces, too_many_ad_accounts or too_much_storage otherwise; nothing is removed or disconnected for you). Monthly to yearly applies now: Stripe starts a yearly period today, bills the year and credits the unused part of this month on the same invoice. It's checked again at the end of the period: when it no longer fits, the plan stays. Enterprise changes go through sales (409, reason: contact_sales). The current plan cancels a scheduled change.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
cadence- The billing period; the current one by default.One of
monthly,yearly plan- The plan.One of
pro,business previewId- The preview this change confirms; required for a change that charges now.
Response
access- What the organization may do now;
noneis read-only.One offull,grace,none accessReason- Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntiladAccounts- used (ad accounts connected across the organization's workspaces, each once, on its busiest platform) and cap (Pro and the trial: 3 per platform; null: no cap). The cap counts per platform: an account new to the organization beyond its platform's cap isn't added by the sync: GET /integrations/{platform} shows it in
adAccountLimit; accounts already connected always stay. adAccountsByPlatform- Connected ad accounts per platform, each once across the organization's workspaces (
{"meta": 2}): only platforms with at least one. billingUrl- The billing page in the app.
catalogue- The plan catalog, the one source of every price, cap and gate (the pricing page): version, currency, yearlyDiscountPercent (20), credits {usdPerCredit, minimumPurchase, rolloverMonths, trialCredits}, trial {days, workspaces, credits}, recommendation {businessBesideProUsdCents, enterpriseFromBusinessYearlyMonthlyUsdCents}, plans [{key, name, productName, unitLabel, description, terms (the plan's terms as strings, snake_case: workspaces, max_members, max_guests, max_ad_accounts, storage_gb, storage_gb_per_extra_workspace, included_usage, included_members, included_workspaces, features, support, …), items [{key, name, product, monthlyUsdCents, yearlyUsdCents, includedQuantity}], storagePrice (null on Pro, or {lookupKey, unitAmountDecimal, perGbMonth, usdPer100GbMonth})}] and enterprise {fromMonthlyUsdCents, includedMembers, includedWorkspaces, creditsBase, creditsPerExtraMember, storageGbDefault, storageGbPerExtraWorkspace, usdPer100GbMonth, slaPercent, support}.
configured- Billing is set up for this deployment.
contactUrl- The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
credits- AI in credits (1 credit = $0.01; whole numbers). Every credit, included, added by Pluto or bought, is valid 12 months unless Pluto set another expiry; unused credits roll over and are used in one order (included, then added by Pluto, then bought; the soonest to expire first within each), only while the plan is active. included (this month's; the trial: 300 in total), used (this month), remaining (usable now), rolledOver (left of earlier months' included credits), bought (left of bought credits), goodwill (left of credits Pluto added), available (used + remaining), perMember (1,200 on Pro, 1,500 on Business; null otherwise), periodStart, nextCreditsAt (next month's included credits; null without a plan), nextExpiry {credits, expiresAt}, alert (
none,almostat 80%,reachedat 100% ofavailable), creditPrice (0.01), value {included, used, remaining} (USD), sources {contract, addedMembers} (Enterprise: the contract's credits a month and 2,000 for each member added during it; null otherwise), lots [{id, source (included,goodwill,purchase,auto_top_up), credits, remaining, addedAt, expiresAt}] in the order they're used, canBuy, buyBlocked (choose_plan: the trial or no plan;complimentary: complimentary access without a card on file), autoTopUp (see PUT …/billing/credits/auto-top-up; null without a plan) and waiting (AI waits for credits now). enforced- Paid access is enforced for this organization.
enterprise- An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (
monthly; an older contract may beyearlyorquarterly), monthlyPrice (one price a month for the whole contract, with the additions paid so far, whole dollars), invoiceAmount (one regular invoice), nextInvoiceAt, nextInvoiceAmount (what that invoice bills, with the additions paid before it)}, members and workspaces {contracted (with paid additions), used, pending (in unpaid additions)}, prices {member, workspace} a month each added during the contract, creativeMemory {included}, autoTopUp {enabled, credits, monthlyCap, usedThisMonth, version}, notices [{metric, threshold, message}]. Beyond the contract a new member or workspace answers402 plan_limitwithreason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions. guests- Guests now: free.
hasCustomer- A Stripe customer exists (the portal opens).
includedUsage- Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoices- Recent invoices.
limits- What the plan (or the trial, or complimentary access) includes: plan, name, workspaces (null: unlimited), maxMembers, maxGuests and maxAdAccounts (Pro and the trial: 5, 10 and 3 ad accounts per platform, per organization; null: unlimited), storageGb (Enterprise: the contract's), storageGbPerExtraWorkspace (Pro 50 up to its 3 workspaces, Business 100, Enterprise 200), includedUsagePerMember, includedMembers, includedWorkspaces, features (
workspace_limits,usage_breakdown,audit_log,workspace_access,extra_storageon Business and Enterprise;sso_scim,invoicing,sla,creative_memoryon Enterprise), support. members- Members now: paid.
nextInvoice- amount, currency, date.
organization- id, name, workspaces [{id, name}], enterprise.
plan- key (
pro,business,enterprise) and name while subscribed; null during the free trial and without a plan. plans- Pro, Business and Enterprise with this organization's numbers.
rates- currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnly- since: read-only since then, until the organization subscribes; nothing is deleted.
recommendation- What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (
proorbusiness, the oneplans[].recommendedmarks, the same at both), businessBesidePro (Pro is recommended and Business costs at most $50 a month more at that period: show it beside Pro), enterpriseSuggested (Business billed yearly costs $500 a month or more: sales is worth a call)}. salesUrl- Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
source- Where access comes from.One of
subscription,trial,complimentary,none status- The Stripe subscription's status.One of
none,trialing,active,past_due,unpaid,canceled,incomplete,incomplete_expired,paused storage- includedGb, includedBytes, usedGb, usedBytes, workspaces [{workspaceId, name, usedGb, usedBytes}], extra {available (Business and Enterprise with a subscription; Pro's storage is fixed), enabled, limit (null: no limit), version, pricePerGbMonth, maxExtraGb, maxExtraBytes (null: no limit), extraGb, extraBytes, costSoFar}. Each GB field is rounded to 2 decimals and each Bytes field is exact (1 GB = 1,073,741,824 bytes, as storage is metered).
subscription- plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
support- The support the organization has now:
email(Email) on the trial and Pro,priority_email(Priority email) on Business,shared_channel(a channel shared with the team) on Enterprise.One ofemail,priority_email,shared_channel syncedAttrial- startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailable- Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspaces- used (active workspaces), cap (the hard limit: the trial 1, Pro 3; null: no cap), included (what the plan's price covers; Enterprise: the contracted workspaces), price (what the next workspace beyond
includedadds: amount, currency, interval; null without one and on Enterprise) and tiers (a graduated workspace price's tiers: from, to, amount, billed; null for a flat price, as on Pro and Business).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403A charge confirmed by an agent or an API key.
- 404Not found in this workspace.
- 409No subscription, an organization that doesn't fit the plan, an Enterprise plan, an expired or moved preview, or a declined card.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/plan" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b4a59eee-28c0-4e1e-9d8e-38931a838a83" \
-H "Content-Type: application/json" \
-d '{
"cadence": "monthly",
"plan": "pro",
"previewId": "83430d4f-edea-4bcc-be8b-ef27c1b67071"
}'Keep the current plan
Cancels a downgrade scheduled for the end of the period.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
access- What the organization may do now;
noneis read-only.One offull,grace,none accessReason- Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntiladAccounts- used (ad accounts connected across the organization's workspaces, each once, on its busiest platform) and cap (Pro and the trial: 3 per platform; null: no cap). The cap counts per platform: an account new to the organization beyond its platform's cap isn't added by the sync: GET /integrations/{platform} shows it in
adAccountLimit; accounts already connected always stay. adAccountsByPlatform- Connected ad accounts per platform, each once across the organization's workspaces (
{"meta": 2}): only platforms with at least one. billingUrl- The billing page in the app.
catalogue- The plan catalog, the one source of every price, cap and gate (the pricing page): version, currency, yearlyDiscountPercent (20), credits {usdPerCredit, minimumPurchase, rolloverMonths, trialCredits}, trial {days, workspaces, credits}, recommendation {businessBesideProUsdCents, enterpriseFromBusinessYearlyMonthlyUsdCents}, plans [{key, name, productName, unitLabel, description, terms (the plan's terms as strings, snake_case: workspaces, max_members, max_guests, max_ad_accounts, storage_gb, storage_gb_per_extra_workspace, included_usage, included_members, included_workspaces, features, support, …), items [{key, name, product, monthlyUsdCents, yearlyUsdCents, includedQuantity}], storagePrice (null on Pro, or {lookupKey, unitAmountDecimal, perGbMonth, usdPer100GbMonth})}] and enterprise {fromMonthlyUsdCents, includedMembers, includedWorkspaces, creditsBase, creditsPerExtraMember, storageGbDefault, storageGbPerExtraWorkspace, usdPer100GbMonth, slaPercent, support}.
configured- Billing is set up for this deployment.
contactUrl- The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
credits- AI in credits (1 credit = $0.01; whole numbers). Every credit, included, added by Pluto or bought, is valid 12 months unless Pluto set another expiry; unused credits roll over and are used in one order (included, then added by Pluto, then bought; the soonest to expire first within each), only while the plan is active. included (this month's; the trial: 300 in total), used (this month), remaining (usable now), rolledOver (left of earlier months' included credits), bought (left of bought credits), goodwill (left of credits Pluto added), available (used + remaining), perMember (1,200 on Pro, 1,500 on Business; null otherwise), periodStart, nextCreditsAt (next month's included credits; null without a plan), nextExpiry {credits, expiresAt}, alert (
none,almostat 80%,reachedat 100% ofavailable), creditPrice (0.01), value {included, used, remaining} (USD), sources {contract, addedMembers} (Enterprise: the contract's credits a month and 2,000 for each member added during it; null otherwise), lots [{id, source (included,goodwill,purchase,auto_top_up), credits, remaining, addedAt, expiresAt}] in the order they're used, canBuy, buyBlocked (choose_plan: the trial or no plan;complimentary: complimentary access without a card on file), autoTopUp (see PUT …/billing/credits/auto-top-up; null without a plan) and waiting (AI waits for credits now). enforced- Paid access is enforced for this organization.
enterprise- An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (
monthly; an older contract may beyearlyorquarterly), monthlyPrice (one price a month for the whole contract, with the additions paid so far, whole dollars), invoiceAmount (one regular invoice), nextInvoiceAt, nextInvoiceAmount (what that invoice bills, with the additions paid before it)}, members and workspaces {contracted (with paid additions), used, pending (in unpaid additions)}, prices {member, workspace} a month each added during the contract, creativeMemory {included}, autoTopUp {enabled, credits, monthlyCap, usedThisMonth, version}, notices [{metric, threshold, message}]. Beyond the contract a new member or workspace answers402 plan_limitwithreason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions. guests- Guests now: free.
hasCustomer- A Stripe customer exists (the portal opens).
includedUsage- Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoices- Recent invoices.
limits- What the plan (or the trial, or complimentary access) includes: plan, name, workspaces (null: unlimited), maxMembers, maxGuests and maxAdAccounts (Pro and the trial: 5, 10 and 3 ad accounts per platform, per organization; null: unlimited), storageGb (Enterprise: the contract's), storageGbPerExtraWorkspace (Pro 50 up to its 3 workspaces, Business 100, Enterprise 200), includedUsagePerMember, includedMembers, includedWorkspaces, features (
workspace_limits,usage_breakdown,audit_log,workspace_access,extra_storageon Business and Enterprise;sso_scim,invoicing,sla,creative_memoryon Enterprise), support. members- Members now: paid.
nextInvoice- amount, currency, date.
organization- id, name, workspaces [{id, name}], enterprise.
plan- key (
pro,business,enterprise) and name while subscribed; null during the free trial and without a plan. plans- Pro, Business and Enterprise with this organization's numbers.
rates- currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnly- since: read-only since then, until the organization subscribes; nothing is deleted.
recommendation- What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (
proorbusiness, the oneplans[].recommendedmarks, the same at both), businessBesidePro (Pro is recommended and Business costs at most $50 a month more at that period: show it beside Pro), enterpriseSuggested (Business billed yearly costs $500 a month or more: sales is worth a call)}. salesUrl- Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
source- Where access comes from.One of
subscription,trial,complimentary,none status- The Stripe subscription's status.One of
none,trialing,active,past_due,unpaid,canceled,incomplete,incomplete_expired,paused storage- includedGb, includedBytes, usedGb, usedBytes, workspaces [{workspaceId, name, usedGb, usedBytes}], extra {available (Business and Enterprise with a subscription; Pro's storage is fixed), enabled, limit (null: no limit), version, pricePerGbMonth, maxExtraGb, maxExtraBytes (null: no limit), extraGb, extraBytes, costSoFar}. Each GB field is rounded to 2 decimals and each Bytes field is exact (1 GB = 1,073,741,824 bytes, as storage is metered).
subscription- plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
support- The support the organization has now:
email(Email) on the trial and Pro,priority_email(Priority email) on Business,shared_channel(a channel shared with the team) on Enterprise.One ofemail,priority_email,shared_channel syncedAttrial- startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailable- Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspaces- used (active workspaces), cap (the hard limit: the trial 1, Pro 3; null: no cap), included (what the plan's price covers; Enterprise: the contracted workspaces), price (what the next workspace beyond
includedadds: amount, currency, interval; null without one and on Enterprise) and tiers (a graduated workspace price's tiers: from, to, amount, billed; null for a flat price, as on Pro and Business).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/plan" \
-H "Authorization: Bearer $PLUTO_KEY"Preview a plan change
What a plan change costs before it's made: dueToday is the invoice Stripe would create for it now (prorated, after credits; 0 for a change that waits for the end of the period, effective: period_end), next the plan's recurring price from the next period, before tax. Confirm it within 10 minutes with POST …/billing/plan and its previewId. Agents and API keys may preview.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
cadence- The billing period; the current one by default.One of
monthly,yearly plan- The plan.One of
pro,business
Response
cadence- The billing period.
dueTodaydueToday.amount- Decimal in the currency's major unit.
dueToday.currency- ISO 4217, lower case.
effective- When it applies.One of
now,period_end expiresAt- Until when it can be confirmed.
nextnext.amount- Decimal in the currency's major unit.
next.currency- ISO 4217, lower case.
next.interval- How often it bills.One of
month,year next.startsAt- When the next period starts.
plan- The plan.
previewId- Confirm the change with this.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409No subscription, an organization that doesn't fit the plan, or an Enterprise plan.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/plan/preview" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"cadence": "monthly",
"plan": "pro"
}'Open the billing portal
A short-lived Stripe customer portal URL: payment methods, invoices, billing details, canceling. Quantities follow the organization, so there's nothing to switch. 409 before the organization has subscribed. An Enterprise agreement can't be canceled mid-term: the cancel flow answers 409 with reason: agreement_term and runsUntil. Only a signed-in person opens it: agents and API keys get 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
flow- Where it opens; manage by default.One of
manage,payment_method,cancel
Response
url- The portal session URL.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The organization has no billing details yet.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/portal" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"flow": "manage"
}'Set extra media storage
The plan's storage is pooled across the organization's workspaces. On Business and Enterprise, extra storage beyond it is billed on the daily average per GB-month ($0.06 on Business, $0.04 on Enterprise), only while it's on and within its monthly limit if one is set (none by default); otherwise uploads wait (plan_limit, feature: media_storage) until extra storage is on or its limit is raised. Pro's storage is fixed: 50 GB, and 50 GB more with each workspace added (402 plan_limit, feature: extra_storage, upgradeTo: business). Needs a subscription, not the trial. Only a signed-in person turns it on or changes it while it's on: agents and API keys get 403; turning it off always works.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
enabled- Extra storage on or off.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
limit- USD per month, such as
13.00; null is no limit.
Response
The storage, as in the billing overview: includedGb, includedBytes, usedGb, usedBytes, workspaces [{workspaceId, name, usedGb, usedBytes}], extra {available, enabled, limit, version, pricePerGbMonth, maxExtraGb, maxExtraBytes, extraGb, extraBytes, costSoFar}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: extra_storage,upgradeTo: business): Pro's storage is fixed, and the trial's. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409No subscription yet.
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/storage" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: cc298304-a758-4145-a113-ec2bb9c7e0f2" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"expectedVersion": 3,
"limit": "150.00"
}'Refresh billing
Fetches the subscription and invoices from Stripe now and returns the same body as GET /organizations/{id}/billing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
access- What the organization may do now;
noneis read-only.One offull,grace,none accessReason- Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntiladAccounts- used (ad accounts connected across the organization's workspaces, each once, on its busiest platform) and cap (Pro and the trial: 3 per platform; null: no cap). The cap counts per platform: an account new to the organization beyond its platform's cap isn't added by the sync: GET /integrations/{platform} shows it in
adAccountLimit; accounts already connected always stay. adAccountsByPlatform- Connected ad accounts per platform, each once across the organization's workspaces (
{"meta": 2}): only platforms with at least one. billingUrl- The billing page in the app.
catalogue- The plan catalog, the one source of every price, cap and gate (the pricing page): version, currency, yearlyDiscountPercent (20), credits {usdPerCredit, minimumPurchase, rolloverMonths, trialCredits}, trial {days, workspaces, credits}, recommendation {businessBesideProUsdCents, enterpriseFromBusinessYearlyMonthlyUsdCents}, plans [{key, name, productName, unitLabel, description, terms (the plan's terms as strings, snake_case: workspaces, max_members, max_guests, max_ad_accounts, storage_gb, storage_gb_per_extra_workspace, included_usage, included_members, included_workspaces, features, support, …), items [{key, name, product, monthlyUsdCents, yearlyUsdCents, includedQuantity}], storagePrice (null on Pro, or {lookupKey, unitAmountDecimal, perGbMonth, usdPer100GbMonth})}] and enterprise {fromMonthlyUsdCents, includedMembers, includedWorkspaces, creditsBase, creditsPerExtraMember, storageGbDefault, storageGbPerExtraWorkspace, usdPer100GbMonth, slaPercent, support}.
configured- Billing is set up for this deployment.
contactUrl- The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
credits- AI in credits (1 credit = $0.01; whole numbers). Every credit, included, added by Pluto or bought, is valid 12 months unless Pluto set another expiry; unused credits roll over and are used in one order (included, then added by Pluto, then bought; the soonest to expire first within each), only while the plan is active. included (this month's; the trial: 300 in total), used (this month), remaining (usable now), rolledOver (left of earlier months' included credits), bought (left of bought credits), goodwill (left of credits Pluto added), available (used + remaining), perMember (1,200 on Pro, 1,500 on Business; null otherwise), periodStart, nextCreditsAt (next month's included credits; null without a plan), nextExpiry {credits, expiresAt}, alert (
none,almostat 80%,reachedat 100% ofavailable), creditPrice (0.01), value {included, used, remaining} (USD), sources {contract, addedMembers} (Enterprise: the contract's credits a month and 2,000 for each member added during it; null otherwise), lots [{id, source (included,goodwill,purchase,auto_top_up), credits, remaining, addedAt, expiresAt}] in the order they're used, canBuy, buyBlocked (choose_plan: the trial or no plan;complimentary: complimentary access without a card on file), autoTopUp (see PUT …/billing/credits/auto-top-up; null without a plan) and waiting (AI waits for credits now). enforced- Paid access is enforced for this organization.
enterprise- An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (
monthly; an older contract may beyearlyorquarterly), monthlyPrice (one price a month for the whole contract, with the additions paid so far, whole dollars), invoiceAmount (one regular invoice), nextInvoiceAt, nextInvoiceAmount (what that invoice bills, with the additions paid before it)}, members and workspaces {contracted (with paid additions), used, pending (in unpaid additions)}, prices {member, workspace} a month each added during the contract, creativeMemory {included}, autoTopUp {enabled, credits, monthlyCap, usedThisMonth, version}, notices [{metric, threshold, message}]. Beyond the contract a new member or workspace answers402 plan_limitwithreason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions. guests- Guests now: free.
hasCustomer- A Stripe customer exists (the portal opens).
includedUsage- Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoices- Recent invoices.
limits- What the plan (or the trial, or complimentary access) includes: plan, name, workspaces (null: unlimited), maxMembers, maxGuests and maxAdAccounts (Pro and the trial: 5, 10 and 3 ad accounts per platform, per organization; null: unlimited), storageGb (Enterprise: the contract's), storageGbPerExtraWorkspace (Pro 50 up to its 3 workspaces, Business 100, Enterprise 200), includedUsagePerMember, includedMembers, includedWorkspaces, features (
workspace_limits,usage_breakdown,audit_log,workspace_access,extra_storageon Business and Enterprise;sso_scim,invoicing,sla,creative_memoryon Enterprise), support. members- Members now: paid.
nextInvoice- amount, currency, date.
organization- id, name, workspaces [{id, name}], enterprise.
plan- key (
pro,business,enterprise) and name while subscribed; null during the free trial and without a plan. plans- Pro, Business and Enterprise with this organization's numbers.
rates- currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnly- since: read-only since then, until the organization subscribes; nothing is deleted.
recommendation- What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (
proorbusiness, the oneplans[].recommendedmarks, the same at both), businessBesidePro (Pro is recommended and Business costs at most $50 a month more at that period: show it beside Pro), enterpriseSuggested (Business billed yearly costs $500 a month or more: sales is worth a call)}. salesUrl- Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
source- Where access comes from.One of
subscription,trial,complimentary,none status- The Stripe subscription's status.One of
none,trialing,active,past_due,unpaid,canceled,incomplete,incomplete_expired,paused storage- includedGb, includedBytes, usedGb, usedBytes, workspaces [{workspaceId, name, usedGb, usedBytes}], extra {available (Business and Enterprise with a subscription; Pro's storage is fixed), enabled, limit (null: no limit), version, pricePerGbMonth, maxExtraGb, maxExtraBytes (null: no limit), extraGb, extraBytes, costSoFar}. Each GB field is rounded to 2 decimals and each Bytes field is exact (1 GB = 1,073,741,824 bytes, as storage is metered).
subscription- plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
support- The support the organization has now:
email(Email) on the trial and Pro,priority_email(Priority email) on Business,shared_channel(a channel shared with the team) on Enterprise.One ofemail,priority_email,shared_channel syncedAttrial- startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailable- Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspaces- used (active workspaces), cap (the hard limit: the trial 1, Pro 3; null: no cap), included (what the plan's price covers; Enterprise: the contracted workspaces), price (what the next workspace beyond
includedadds: amount, currency, interval; null without one and on Enterprise) and tiers (a graduated workspace price's tiers: from, to, amount, billed; null for a flat price, as on Pro and Business).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/sync" \
-H "Authorization: Bearer $PLUTO_KEY"Add a tax ID
Stripe checks the format now and verifies EU VAT, GB VAT and AU ABN numbers with the tax authority afterwards. An EU business with a VAT ID in another EU country is invoiced with reverse charge.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
type- Stripe's tax ID type, such as
eu_vat,gb_vat,no_vat,ch_vat,au_abn,ca_gst_hst. value- The tax ID.
Response
address- line1, line2, city, postalCode, state, country.
email- Receives invoices and receipts.
name- The business name on invoices.
paymentTermscard: charged automatically;net_30: invoices are sent and due in 30 days (Enterprise).One ofcard,net_30poNumber- Enterprise: the purchase order number printed on every invoice.
taxExempt- Stripe's tax exemption.One of
none,exempt,reverse taxIds- Tax IDs.
taxStatus- Whether tax can be calculated from the address (
address_needed: add or complete it).One ofready,address_needed,not_collecting
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/tax-ids" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "eu_vat",
"value": "4210.00"
}'Remove a tax ID
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
tax_id | string | Required | The tax's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
address- line1, line2, city, postalCode, state, country.
email- Receives invoices and receipts.
name- The business name on invoices.
paymentTermscard: charged automatically;net_30: invoices are sent and due in 30 days (Enterprise).One ofcard,net_30poNumber- Enterprise: the purchase order number printed on every invoice.
taxExempt- Stripe's tax exemption.One of
none,exempt,reverse taxIds- Tax IDs.
taxStatus- Whether tax can be calculated from the address (
address_needed: add or complete it).One ofready,address_needed,not_collecting
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/tax-ids/txi_Uggh2nAEmkUGhxNlqwt5TalJ" \
-H "Authorization: Bearer $PLUTO_KEY"Start the free trial
Starts the free trial of an organization without a plan that never had a trial or a subscription (trialAvailable in the overview). Returns the same body as GET /organizations/{id}/billing; while a trial already runs it changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
access- What the organization may do now;
noneis read-only.One offull,grace,none accessReason- Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntiladAccounts- used (ad accounts connected across the organization's workspaces, each once, on its busiest platform) and cap (Pro and the trial: 3 per platform; null: no cap). The cap counts per platform: an account new to the organization beyond its platform's cap isn't added by the sync: GET /integrations/{platform} shows it in
adAccountLimit; accounts already connected always stay. adAccountsByPlatform- Connected ad accounts per platform, each once across the organization's workspaces (
{"meta": 2}): only platforms with at least one. billingUrl- The billing page in the app.
catalogue- The plan catalog, the one source of every price, cap and gate (the pricing page): version, currency, yearlyDiscountPercent (20), credits {usdPerCredit, minimumPurchase, rolloverMonths, trialCredits}, trial {days, workspaces, credits}, recommendation {businessBesideProUsdCents, enterpriseFromBusinessYearlyMonthlyUsdCents}, plans [{key, name, productName, unitLabel, description, terms (the plan's terms as strings, snake_case: workspaces, max_members, max_guests, max_ad_accounts, storage_gb, storage_gb_per_extra_workspace, included_usage, included_members, included_workspaces, features, support, …), items [{key, name, product, monthlyUsdCents, yearlyUsdCents, includedQuantity}], storagePrice (null on Pro, or {lookupKey, unitAmountDecimal, perGbMonth, usdPer100GbMonth})}] and enterprise {fromMonthlyUsdCents, includedMembers, includedWorkspaces, creditsBase, creditsPerExtraMember, storageGbDefault, storageGbPerExtraWorkspace, usdPer100GbMonth, slaPercent, support}.
configured- Billing is set up for this deployment.
contactUrl- The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
credits- AI in credits (1 credit = $0.01; whole numbers). Every credit, included, added by Pluto or bought, is valid 12 months unless Pluto set another expiry; unused credits roll over and are used in one order (included, then added by Pluto, then bought; the soonest to expire first within each), only while the plan is active. included (this month's; the trial: 300 in total), used (this month), remaining (usable now), rolledOver (left of earlier months' included credits), bought (left of bought credits), goodwill (left of credits Pluto added), available (used + remaining), perMember (1,200 on Pro, 1,500 on Business; null otherwise), periodStart, nextCreditsAt (next month's included credits; null without a plan), nextExpiry {credits, expiresAt}, alert (
none,almostat 80%,reachedat 100% ofavailable), creditPrice (0.01), value {included, used, remaining} (USD), sources {contract, addedMembers} (Enterprise: the contract's credits a month and 2,000 for each member added during it; null otherwise), lots [{id, source (included,goodwill,purchase,auto_top_up), credits, remaining, addedAt, expiresAt}] in the order they're used, canBuy, buyBlocked (choose_plan: the trial or no plan;complimentary: complimentary access without a card on file), autoTopUp (see PUT …/billing/credits/auto-top-up; null without a plan) and waiting (AI waits for credits now). enforced- Paid access is enforced for this organization.
enterprise- An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (
monthly; an older contract may beyearlyorquarterly), monthlyPrice (one price a month for the whole contract, with the additions paid so far, whole dollars), invoiceAmount (one regular invoice), nextInvoiceAt, nextInvoiceAmount (what that invoice bills, with the additions paid before it)}, members and workspaces {contracted (with paid additions), used, pending (in unpaid additions)}, prices {member, workspace} a month each added during the contract, creativeMemory {included}, autoTopUp {enabled, credits, monthlyCap, usedThisMonth, version}, notices [{metric, threshold, message}]. Beyond the contract a new member or workspace answers402 plan_limitwithreason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions. guests- Guests now: free.
hasCustomer- A Stripe customer exists (the portal opens).
includedUsage- Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoices- Recent invoices.
limits- What the plan (or the trial, or complimentary access) includes: plan, name, workspaces (null: unlimited), maxMembers, maxGuests and maxAdAccounts (Pro and the trial: 5, 10 and 3 ad accounts per platform, per organization; null: unlimited), storageGb (Enterprise: the contract's), storageGbPerExtraWorkspace (Pro 50 up to its 3 workspaces, Business 100, Enterprise 200), includedUsagePerMember, includedMembers, includedWorkspaces, features (
workspace_limits,usage_breakdown,audit_log,workspace_access,extra_storageon Business and Enterprise;sso_scim,invoicing,sla,creative_memoryon Enterprise), support. members- Members now: paid.
nextInvoice- amount, currency, date.
organization- id, name, workspaces [{id, name}], enterprise.
plan- key (
pro,business,enterprise) and name while subscribed; null during the free trial and without a plan. plans- Pro, Business and Enterprise with this organization's numbers.
rates- currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnly- since: read-only since then, until the organization subscribes; nothing is deleted.
recommendation- What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (
proorbusiness, the oneplans[].recommendedmarks, the same at both), businessBesidePro (Pro is recommended and Business costs at most $50 a month more at that period: show it beside Pro), enterpriseSuggested (Business billed yearly costs $500 a month or more: sales is worth a call)}. salesUrl- Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
source- Where access comes from.One of
subscription,trial,complimentary,none status- The Stripe subscription's status.One of
none,trialing,active,past_due,unpaid,canceled,incomplete,incomplete_expired,paused storage- includedGb, includedBytes, usedGb, usedBytes, workspaces [{workspaceId, name, usedGb, usedBytes}], extra {available (Business and Enterprise with a subscription; Pro's storage is fixed), enabled, limit (null: no limit), version, pricePerGbMonth, maxExtraGb, maxExtraBytes (null: no limit), extraGb, extraBytes, costSoFar}. Each GB field is rounded to 2 decimals and each Bytes field is exact (1 GB = 1,073,741,824 bytes, as storage is metered).
subscription- plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
support- The support the organization has now:
email(Email) on the trial and Pro,priority_email(Priority email) on Business,shared_channel(a channel shared with the team) on Enterprise.One ofemail,priority_email,shared_channel syncedAttrial- startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailable- Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspaces- used (active workspaces), cap (the hard limit: the trial 1, Pro 3; null: no cap), included (what the plan's price covers; Enterprise: the contracted workspaces), price (what the next workspace beyond
includedadds: amount, currency, interval; null without one and on Enterprise) and tiers (a graduated workspace price's tiers: from, to, amount, billed; null for a flat price, as on Pro and Business).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409No trial is available (
reason: trial_unavailable): choose a plan. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/trial" \
-H "Authorization: Bearer $PLUTO_KEY"Get the cost of each workspace
What each workspace cost in a billing period, so an agency can rebill its clients: fee (its share of the workspace add-on: 0.00 for the workspaces the plan includes, prorated when added or removed mid-period), aiIncluded (what the plan's included credits paid for its Agent, Loops and Creative Memory usage; AI is paid by credits, never on an invoice), storage and total (fee + storage). Archived and deleted workspaces are listed when they cost something in the period. The Shared row (workspaceId: null) holds what no workspace causes: the plan's base price, members, extra media storage (pooled across the organization) and adjustments, so the rows add up to the period's charges before tax (invoiced). With invoice, the same rows for exactly that invoice (the per-client statement its footer points to): its lines net of the credits and discounts on it, so totals.total equals the invoice's total before tax to the cent; another organization's invoice is 404. format=csv or Accept: text/csv answers the same rows as CSV with the columns period_start, period_end, workspace_id, workspace, status, fee, ai_included, storage, total, currency, stored_bytes, storage_gb_months. Business, like the usage CSV export.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
period | string | Optional | current (default), previous, or a billing period's id from cycles. |
from | string | Optional | A UTC date range instead of period: first day, YYYY-MM-DD. |
to | string | Optional | Last day, YYYY-MM-DD (inclusive; at most 400 days after from). |
invoice | string | Optional | One invoice's statement instead of a period: an invoice id (in_…) from the billing overview's invoices. |
format | string | Optional | json (default) or csv. |
bom | string | Optional | true starts the CSV with a UTF-8 byte order mark, for a file a person opens: Excel then reads accented and non-Latin letters correctly. Leave it out when a program reads the CSV. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
currencyusd.cycles- The organization's billing periods, newest first.
invoiced- What Stripe bills for the period before tax (its invoices and, for the current period, the preview of the next invoice); null without a subscription.
totals.totalequals it once the period's storage is metered. For an invoice: its total before tax. items- One row per workspace, oldest first, then
Shared. organizationId- Organization ID.
period- id (pass as
period; null for a date range or an invoice), start, end. planpro,businessorenterprise; null during the trial and without a plan.totals- fee, aiIncluded, storage, total.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: usage_breakdown,upgradeTo: business): cost per workspace comes with Business. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/billing/workspace-costs" \
-H "Authorization: Bearer $PLUTO_KEY"Get usage
Agent, Loops and Creative Memory usage this month (UTC) in credits: what included and bought credits paid, per source and per day, and on Business per workspace (its members, the Agent and each loop; byWorkspace is empty on other plans). totals adds the filtered usage's tokens; webSearches counts the web searches the AI made in the same range. Members see their own usage only; guests have no access.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
period | string | Optional | current (default) or previous. |
workspaceId | string | Optional | Only this workspace (Business; 402 plan_limit on other plans). |
agentId | string | Optional | Only this connected agent: the MCP client's, agent client's or API key's ID, as in by=agent (Business; 402 plan_limit on other plans). |
userId | string | Optional | Only this member (owners and admins). |
source | string | Optional | human, agent, loop, api_mcp or creative_memory. |
loopId | string | Optional | Only this loop. |
model | string | Optional | Only this model. |
q | string | Optional | Search members, sources, models and workspaces. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
scope, period, members, trial, readOnly, rates, included, used, limitReached, stopReason (credits_used: AI waits for credits; trial_cap), bySource, byWorkspace, byDay, nextCreditsAt, totals (amount, included, bought, freeRequests, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, webSearches), webSearches, credits (available, used, remaining).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage" \
-H "Authorization: Bearer $PLUTO_KEY"Get a usage breakdown
Break usage down.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
by | string | Optional | member (default), source, loop, model or type on every plan; on Business workspace and agent (each connected agent: MCP client, agent client or API key, keyed by its ID and named by it). |
period | string | Optional | current (default) or previous. |
workspaceId | string | Optional | Only this workspace (Business). |
userId | string | Optional | Only this member (owners and admins). |
source | string | Optional | human, agent, loop, api_mcp or creative_memory. |
loopId | string | Optional | Only this loop. |
agentId | string | Optional | Only this connected agent (Business). |
model | string | Optional | Only this model. |
q | string | Optional | Search. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
by- The breakdown.
items- Largest first.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: usage_breakdown,upgradeTo: business): by workspace or connected agent, or a workspace or connected-agent filter, on a plan without Business. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/breakdown" \
-H "Authorization: Bearer $PLUTO_KEY"Export usage as CSV
The period's usage events as CSV, with the same scope and filters as the events list: workspace, member, source and its name (the connected agent for api_mcp), model, tokens and charge, streamed as it's read. POST /organizations/{id}/usage/exports writes the same file in the background, follows its progress and notifies when it's ready; prefer that for a large organization. Business.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
period | string | Optional | current (default) or previous. |
workspaceId | string | Optional | Only this workspace (Business; 402 plan_limit on other plans). |
agentId | string | Optional | Only this connected agent: the MCP client's, agent client's or API key's ID, as in by=agent (Business; 402 plan_limit on other plans). |
userId | string | Optional | Only this member (owners and admins). |
source | string | Optional | human, agent, loop, api_mcp or creative_memory. |
loopId | string | Optional | Only this loop. |
model | string | Optional | Only this model. |
q | string | Optional | Search members, sources, models and workspaces. |
bom | string | Optional | true starts the CSV with a UTF-8 byte order mark, for a file a person opens: Excel then reads accented and non-Latin letters correctly. Leave it out when a program reads the CSV. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
CSV (text/csv).
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: usage_breakdown,upgradeTo: business): the CSV export comes with Business. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/export" \
-H "Authorization: Bearer $PLUTO_KEY"Start a usage export
Export usage events in the background.
Starts a CSV export of the period's usage events (the same scope, filters and columns as GET /organizations/{id}/usage/export) and answers 202 with the export (kind: "usage"). It runs in the background: the job (jobId) counts the events, then writes every one of them, and rowsWritten of rowsTotal says how far it got. Read it with GET /exports/{id}, which gives downloadUrl once it's done; downloads end 7 days later. Asking again with the same filters while one is queued or running returns that one. The file has no byte order mark unless bom is true (for a person opening it in a spreadsheet). The person who asked gets an Inbox notice when it's ready, and an email too when it ran longer than 30 seconds or holds more than 250,000 events (emailWhenReady). Recorded in the organization's audit log once the file is written (billing.usage_exported). Business; owners and admins (and whoever can view billing) export everyone's usage, members their own. It runs in the workspace your credential works in, which must be an active one of the organization (409 otherwise).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
agentId- Only this connected agent: its credential's ID.
bom- Start the file with a UTF-8 byte order mark, for a person opening it in a spreadsheet.
from- A UTC date range instead of
period: first day, YYYY-MM-DD. gzip- Compress the file with gzip (
.csv.gz). loopId- Only this loop.
model- Only this model.
period- Billing period; current by default.One of
current,previous q- Search members, sources, models and workspaces.
source- Only this source.One of
human,agent,loop,api_mcp,creative_memory to- Last day, YYYY-MM-DD (inclusive).
userId- Only this member (owners and admins).
workspaceId- Only this workspace (Business).
Response
bom- The file starts with a UTF-8 byte order mark, so a spreadsheet reads accented and non-Latin letters correctly.
bytes- The file's size, once written.
createdAt- When it was asked for.
downloadUrl- A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReady- It runs longer than 30 seconds or holds more than 250,000 rows, or the app's page that asked for it was left before it was ready: the person who asked also gets an email when it's ready.
error- Why it failed.
expired- Past
expiresAt: the file is gone. expiresAt- When downloads end: 7 days after it was written.
fileName- The file's name.
filters- What it applies, as checked.
finishedAt- When it was written, or failed.
gzip- The file is gzipped (
.csv.gz). id- The export.
jobId- The job that writes it: follow it with
GET /jobs/{id}(MCPwait_for_job). kind- What it holds: the audit log, a workspace's launches, ad sets and ads, or usage events.One of
audit_log,workspace,usage organizationId- The organization it's of; null for a workspace's audit log.
rowsTotal- The rows it holds, once counted (null before); the file's own count once it's written.
rowsWritten- The rows in the file so far.
statusdone: the file is written and can be downloaded untilexpiresAt.One ofqueued,running,done,failedworkspaceId- The workspace a workspace export is of; null for other kinds.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: usage_breakdown,upgradeTo: business): the CSV export comes with Business. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409
conflict: asked from a workspace that isn't an active one of the organization, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/exports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b8fcdfd0-83f0-4706-9e60-d118c13d9f85" \
-H "Content-Type: application/json" \
-d '{
"agentId": "8558d35e-8143-44d2-ac4e-c3ccd5ce664f",
"bom": true,
"from": "2026-09-01",
"gzip": true,
"loopId": "94956d8d-acdf-4e32-b384-25d0b605c2a9",
"model": "pluto",
"period": "current",
"q": "vitamin c serum",
"source": "human",
"to": "2026-09-27",
"userId": "66edca53-0813-467f-bdb8-313e9ad9882f",
"workspaceId": "f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6"
}'Get usage limits
Each workspace's, member's and loop's monthly limit with its use. workspaceLimits says whether the plan applies workspace limits (Business).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
loops- Each Loop's monthly credit cap: at it the Loop's AI steps stop (
spend_limit,reason: loop_limit) and its other steps keep running. members- Each member's monthly limit.
organizationId- The organization.
period- start, end.
workspaceLimits- Whether the plan applies workspace limits (Business and up). Without it,
workspacesstill lists limits kept from Business: they don't apply, and each can be removed. workspaces- Each workspace's monthly limit.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/limits" \
-H "Authorization: Bearer $PLUTO_KEY"Set a Loop cap
Caps one Loop's credits per billing period (every plan); null removes it. At the cap its AI steps stop (spend_limit, reason: loop_limit) and its other steps keep running. A stale version is a 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
loop_id | string | Required | The loop's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
credits- Whole credits per billing period; null removes the cap.
version- The cap's
versionfrom GET /organizations/{id}/usage/limits (0 without one); leave out to overwrite.
Response
loops- Each Loop's monthly credit cap: at it the Loop's AI steps stop (
spend_limit,reason: loop_limit) and its other steps keep running. members- Each member's monthly limit.
organizationId- The organization.
period- start, end.
workspaceLimits- Whether the plan applies workspace limits (Business and up). Without it,
workspacesstill lists limits kept from Business: they don't apply, and each can be removed. workspaces- Each workspace's monthly limit.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/limits/loops/94956d8d-acdf-4e32-b384-25d0b605c2a9" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7aec3903-25e2-47f8-ac56-b9228c41a0b0" \
-H "Content-Type: application/json" \
-d '{
"credits": 3,
"version": 3
}'Set a member's usage limit
Limits one member's Agent and Loops usage per month; null removes it. Over it: spend_limit, reason: member_limit.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
user_id | string | Required | The user's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
limit- USD per month, such as
100.00; null removes it.
Response
loops- Each Loop's monthly credit cap: at it the Loop's AI steps stop (
spend_limit,reason: loop_limit) and its other steps keep running. members- Each member's monthly limit.
organizationId- The organization.
period- start, end.
workspaceLimits- Whether the plan applies workspace limits (Business and up). Without it,
workspacesstill lists limits kept from Business: they don't apply, and each can be removed. workspaces- Each workspace's monthly limit.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/limits/members/66edca53-0813-467f-bdb8-313e9ad9882f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 9dcf39ec-e11a-4d8a-97bb-bf7b679e0068" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"limit": "150.00"
}'Set a workspace's usage limit
Business: limits the workspace's Agent and Loops usage per month; the next Agent or Loops call over it is refused with spend_limit, reason: workspace_limit. null removes it, on every plan. After a move to Pro a workspace limit is kept but no longer applies; it applies again on Business.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
workspace_id | string | Required | The workspace's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
limit- USD per month, such as
100.00; null removes it.
Response
loops- Each Loop's monthly credit cap: at it the Loop's AI steps stop (
spend_limit,reason: loop_limit) and its other steps keep running. members- Each member's monthly limit.
organizationId- The organization.
period- start, end.
workspaceLimits- Whether the plan applies workspace limits (Business and up). Without it,
workspacesstill lists limits kept from Business: they don't apply, and each can be removed. workspaces- Each workspace's monthly limit.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: workspace_limits,upgradeTo: business): setting a workspace limit on a plan without Business. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/limits/workspaces/f4d5c9f7-cd2c-47b5-a2d8-0925fb4909c6" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c421025f-629b-4b25-9b9f-97b9a030740d" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"limit": "150.00"
}'List usage events
Newest first: who, which source and its name (the connected agent for api_mcp), provider, model, tokens and charge, and on Business which workspace (workspaceId and workspace are null on other plans).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
after | string | Optional | Cursor from the previous page. |
limit | string | Optional | 1 to 500; 50 by default. |
period | string | Optional | current (default) or previous. |
workspaceId | string | Optional | Only this workspace (Business). |
userId | string | Optional | Only this member (owners and admins). |
source | string | Optional | human, agent, loop, api_mcp or creative_memory. |
loopId | string | Optional | Only this loop. |
agentId | string | Optional | Only this connected agent (Business). |
model | string | Optional | Only this model. |
q | string | Optional | Search. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
nextAfter
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: usage_breakdown): a workspace or connected-agent filter on a plan without Business. - 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/usage/records" \
-H "Authorization: Bearer $PLUTO_KEY"Contact sales about Enterprise
Sends an Enterprise enquiry to the sales team (stored, and emailed to them). Any member of the organization; guests get 403. Three per organization an hour, else 429. The team answers by email within one business day.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The organization's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
email- A work email to answer.
members- How many members, roughly.
message- What they need, up to 5,000 characters.
name- Who to answer, 1-200 characters.
organization- The company's name, 1-200 characters.
workspaces- How many workspaces, roughly.
Response
createdAt- When it was sent.
id- The enquiry.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/organizations/53049894-aea5-4397-ae7b-c978d151ec95/sales-leads" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: acea49e5-b6f4-4920-86ed-5df238896844" \
-H "Content-Type: application/json" \
-d '{
"email": "maya@brevanne.com",
"members": 12,
"message": "Can we try the 4x5 cut for Instagram feed before we publish?",
"name": "Brevanne",
"organization": "Brevanne",
"workspaces": 12
}'List model rates
Every model's usage rates in USD: per million input, cache write, cache read and output tokens, and per 1,000 web searches where a model searches.
Response
currency- usd
models- Models.
Errors
- 400The request is malformed.
curl "$PLUTO_API/billing/rates"Get this workspace's usage
The current workspace's Agent and Loops usage this month (UTC), its monthly limit if the organization set one, its stored media and usage per person. Whoever can view the organization's billing (billing:read: its owners and admins, the Billing role) sees everyone's usage in the workspace (scope: workspace); others see their own (scope: own). Cost per workspace is a Business feature: 402 plan_limit (feature: usage_breakdown, upgradeTo: business) on other plans, where the organization's usage shows usage per member and source. Guests: 403.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
admin- An organization owner or admin: may set the workspace's limit.
limit- The workspace's monthly limit (USD); null: none.
limitVersion- Pass as
expectedVersionwhen setting the limit. members- Usage per person, highest first.
members[].amount- USD this period.
members[].id- User ID.
members[].name- Name.
organizationorganization.id- Organization ID.
organization.name- Name.
periodperiod.end- RFC 3339.
period.start- RFC 3339.
scopeworkspaceorown.storageBytes- The same in exact bytes (1 GB = 1,073,741,824 bytes, as storage is metered).
storageGb- This workspace's stored media, decimal GB (2 decimals).
used- USD this period, in
scope. workspaceworkspace.id- Workspace ID.
workspace.name- Name.
workspaceUsed- Admins: the workspace's usage against its limit.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: usage_breakdown,upgradeTo: business): cost per workspace comes with Business. - 403The credential lacks the permission, or belongs to another workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/workspace/usage" \
-H "Authorization: Bearer $PLUTO_KEY"