API reference

Billing

An organization's subscription, plan, usage and limits.

GET/organizations/{id}/billing

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accessstringRequired
What the organization may do now; none is read-only.One of full, grace, none
accessReasonstringRequired
Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntilstring (date-time) or null
adAccountsobjectRequired
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.
adAccountsByPlatformobjectRequired
Connected ad accounts per platform, each once across the organization's workspaces ({"meta": 2}): only platforms with at least one.
billingUrlstringRequired
The billing page in the app.
catalogueobjectRequired
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}.
configuredbooleanRequired
Billing is set up for this deployment.
contactUrlstring
The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
creditsobject
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, almost at 80%, reached at 100% of available), 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).
enforcedbooleanRequired
Paid access is enforced for this organization.
enterpriseobject or null
An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (monthly; an older contract may be yearly or quarterly), 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 answers 402 plan_limit with reason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions.
guestsintegerRequired
Guests now: free.
hasCustomerboolean
A Stripe customer exists (the portal opens).
includedUsagestringRequired
Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoicesarray of objectsRequired
Recent invoices.
limitsobjectRequired
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_storage on Business and Enterprise; sso_scim, invoicing, sla, creative_memory on Enterprise), support.
membersintegerRequired
Members now: paid.
nextInvoiceobject or null
amount, currency, date.
organizationobjectRequired
id, name, workspaces [{id, name}], enterprise.
planobject or null
key (pro, business, enterprise) and name while subscribed; null during the free trial and without a plan.
plansarray of objectsRequired
Pro, Business and Enterprise with this organization's numbers.
ratesobjectRequired
currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnlyobject or null
since: read-only since then, until the organization subscribes; nothing is deleted.
recommendationobjectRequired
What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (pro or business, the one plans[].recommended marks, 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)}.
salesUrlstring
Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
sourcestringRequired
Where access comes from.One of subscription, trial, complimentary, none
statusstringRequired
The Stripe subscription's status.One of none, trialing, active, past_due, unpaid, canceled, incomplete, incomplete_expired, paused
storageobjectRequired
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).
subscriptionobject or null
plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
supportstring
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 of email, priority_email, shared_channel
syncedAtstring (date-time) or null
trialobject or null
startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailableboolean
Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspacesobjectRequired
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 included adds: 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-After seconds. 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"
POST/organizations/{id}/billing/checkout

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).

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

cadencestringRequired
Billing period; yearly is 20% off, billed for the year up front.One of monthly, yearly
planstringRequired
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

Response201 Created

urlstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
GET/organizations/{id}/billing/credits

List credit purchases

Purchases and auto top-ups (never the monthly grants), newest first.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

purchasesarray of objectsRequired
Newest first.
purchases[].amountstringRequired
Its price: $0.01 a credit.
purchases[].createdAtstring
RFC 3339.
purchases[].creditsintegerRequired
Credits bought.
purchases[].currencystring
usd.
purchases[].expiresAtstring or null
12 months after it became usable.
purchases[].idstring (uuid)Required
The purchase.
purchases[].invoiceobject or null
id, number, status, hostedInvoiceUrl.
purchases[].paidAtstring or null
When it was paid.
purchases[].problemstring or null
payment_failed: the card was declined (pay the invoice or update the card); no_payment_method: an auto top-up found no card.One of payment_failed, no_payment_method
purchases[].remaininginteger
Credits left on it.
purchases[].sourcestringRequired
Bought by an admin, or by auto top-up.One of purchase, auto_top_up
purchases[].statusstringRequired
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-After seconds. 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"
POST/organizations/{id}/billing/credits

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

creditsintegerRequired
Any whole number from 1,000 to 10,000,000.

Response200 OK

amountstringRequired
Its price: $0.01 a credit.
createdAtstring
RFC 3339.
creditsintegerRequired
Credits bought.
currencystring
usd.
expiresAtstring or null
12 months after it became usable.
idstring (uuid)Required
The purchase.
invoiceobject or null
id, number, status, hostedInvoiceUrl.
paidAtstring or null
When it was paid.
problemstring or null
payment_failed: the card was declined (pay the invoice or update the card); no_payment_method: an auto top-up found no card.One of payment_failed, no_payment_method
remaininginteger
Credits left on it.
sourcestringRequired
Bought by an admin, or by auto top-up.One of purchase, auto_top_up
statusstringRequired
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.
  • 409choose_plan or complimentary: credits can't be bought now.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
PUT/organizations/{id}/billing/credits/auto-top-up

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

creditsinteger
Credits a top-up buys: any whole number from 1,000.
enabledbooleanRequired
On or off.
monthlyCapstring or null
USD of top-ups per calendar month, whole dollars, such as 1000.00; null removes the cap; absent keeps it.
versioninteger
The setting's version (0 before the first change).

Response200 OK

creditsintegerRequired
Credits a top-up buys.
enabledbooleanRequired
On or off (off by default).
inFlightobject or null
The top-up being charged (at most one): id, credits, amount, createdAt, problem (payment_failed or null), invoice.
monthlyCapstring or nullRequired
USD of top-ups per calendar month; null: no cap.
usedThisMonthstringRequired
USD topped up this month.
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/organizations/{id}/billing/details

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

addressobjectRequired
line1, line2, city, postalCode, state, country.
emailstring or null
Receives invoices and receipts.
namestring or null
The business name on invoices.
paymentTermsstringRequired
card: charged automatically; net_30: invoices are sent and due in 30 days (Enterprise).One of card, net_30
poNumberstring or null
Enterprise: the purchase order number printed on every invoice.
taxExemptstringRequired
Stripe's tax exemption.One of none, exempt, reverse
taxIdsarray of objectsRequired
Tax IDs.
taxStatusstringRequired
Whether tax can be calculated from the address (address_needed: add or complete it).One of ready, 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-After seconds. 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"
PUT/organizations/{id}/billing/details

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).

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe 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

addressobject
line1, line2, city, postalCode, state, country (two letters).
emailstring
Receives invoices and receipts.
namestring
The organization's legal or billing name on invoices (a business, not a person).
poNumberstring or null
Enterprise: a purchase order number (1–40 characters) printed on every invoice; null removes it.

Response200 OK

addressobjectRequired
line1, line2, city, postalCode, state, country.
emailstring or null
Receives invoices and receipts.
namestring or null
The business name on invoices.
paymentTermsstringRequired
card: charged automatically; net_30: invoices are sent and due in 30 days (Enterprise).One of card, net_30
poNumberstring or null
Enterprise: the purchase order number printed on every invoice.
taxExemptstringRequired
Stripe's tax exemption.One of none, exempt, reverse
taxIdsarray of objectsRequired
Tax IDs.
taxStatusstringRequired
Whether tax can be calculated from the address (address_needed: add or complete it).One of ready, 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-After seconds. 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"
  }'
GET/organizations/{id}/billing/enterprise/additions

List additions

Enterprise: every addition, newest first, with its invoice.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

additionsarray of objectsRequired
Newest first.
additions[].createdAtstring
RFC 3339.
additions[].currencystring
usd.
additions[].idstring (uuid)Required
The addition.
additions[].invoiceobject or null
id, number, status, hostedInvoiceUrl (where it's paid).
additions[].membersintegerRequired
Members added.
additions[].nextInvoiceAtstring
From this invoice on it's part of every invoice.
additions[].paidAtstring or null
When the invoice was paid.
additions[].statusstringRequired
Active only once the invoice is paid.One of pending_payment, active, void
additions[].totalstringRequired
Invoiced, before tax.
additions[].workspacesintegerRequired
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-After seconds. 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"
POST/organizations/{id}/billing/enterprise/additions

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

expectedTotalstring
The quote's total the admin agreed to.
membersinteger
Members to add (0 or more).
workspacesinteger
Workspaces to add (0 or more).

Response200 OK

createdAtstring
RFC 3339.
currencystring
usd.
idstring (uuid)Required
The addition.
invoiceobject or null
id, number, status, hostedInvoiceUrl (where it's paid).
membersintegerRequired
Members added.
nextInvoiceAtstring
From this invoice on it's part of every invoice.
paidAtstring or null
When the invoice was paid.
statusstringRequired
Active only once the invoice is paid.One of pending_payment, active, void
totalstringRequired
Invoiced, before tax.
workspacesintegerRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
POST/organizations/{id}/billing/enterprise/additions/quote

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe 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

membersinteger
Members to add (0 or more).
workspacesinteger
Workspaces to add (0 or more).

Response200 OK

creditsPerMonthinteger
AI credits a month the added members bring (2,000 each).
currencystringRequired
usd.
daysLeftintegerRequired
Days left until the next invoice, today included.
linesarray of objectsRequired
Members, then workspaces. The amounts add up to the total.
monthlyIncreasestringRequired
What every invoice's month grows by from the next invoice, before tax.
nextInvoiceAtstringRequired
The next invoice: from it on the addition is part of every invoice (RFC 3339).
periodDaysintegerRequired
Days in the invoice period.
periodStartsAtstringRequired
When the invoice period it's charged for started (RFC 3339).
storageGbinteger
Storage the added workspaces bring, GB (200 each).
totalstringRequired
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-After seconds. 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
  }'
POST/organizations/{id}/billing/plan

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

cadencestring
The billing period; the current one by default.One of monthly, yearly
planstringRequired
The plan.One of pro, business
previewIdstring
The preview this change confirms; required for a change that charges now.

Response200 OK

accessstringRequired
What the organization may do now; none is read-only.One of full, grace, none
accessReasonstringRequired
Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntilstring (date-time) or null
adAccountsobjectRequired
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.
adAccountsByPlatformobjectRequired
Connected ad accounts per platform, each once across the organization's workspaces ({"meta": 2}): only platforms with at least one.
billingUrlstringRequired
The billing page in the app.
catalogueobjectRequired
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}.
configuredbooleanRequired
Billing is set up for this deployment.
contactUrlstring
The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
creditsobject
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, almost at 80%, reached at 100% of available), 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).
enforcedbooleanRequired
Paid access is enforced for this organization.
enterpriseobject or null
An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (monthly; an older contract may be yearly or quarterly), 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 answers 402 plan_limit with reason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions.
guestsintegerRequired
Guests now: free.
hasCustomerboolean
A Stripe customer exists (the portal opens).
includedUsagestringRequired
Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoicesarray of objectsRequired
Recent invoices.
limitsobjectRequired
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_storage on Business and Enterprise; sso_scim, invoicing, sla, creative_memory on Enterprise), support.
membersintegerRequired
Members now: paid.
nextInvoiceobject or null
amount, currency, date.
organizationobjectRequired
id, name, workspaces [{id, name}], enterprise.
planobject or null
key (pro, business, enterprise) and name while subscribed; null during the free trial and without a plan.
plansarray of objectsRequired
Pro, Business and Enterprise with this organization's numbers.
ratesobjectRequired
currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnlyobject or null
since: read-only since then, until the organization subscribes; nothing is deleted.
recommendationobjectRequired
What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (pro or business, the one plans[].recommended marks, 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)}.
salesUrlstring
Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
sourcestringRequired
Where access comes from.One of subscription, trial, complimentary, none
statusstringRequired
The Stripe subscription's status.One of none, trialing, active, past_due, unpaid, canceled, incomplete, incomplete_expired, paused
storageobjectRequired
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).
subscriptionobject or null
plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
supportstring
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 of email, priority_email, shared_channel
syncedAtstring (date-time) or null
trialobject or null
startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailableboolean
Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspacesobjectRequired
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 included adds: 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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
DELETE/organizations/{id}/billing/plan

Keep the current plan

Cancels a downgrade scheduled for the end of the period.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accessstringRequired
What the organization may do now; none is read-only.One of full, grace, none
accessReasonstringRequired
Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntilstring (date-time) or null
adAccountsobjectRequired
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.
adAccountsByPlatformobjectRequired
Connected ad accounts per platform, each once across the organization's workspaces ({"meta": 2}): only platforms with at least one.
billingUrlstringRequired
The billing page in the app.
catalogueobjectRequired
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}.
configuredbooleanRequired
Billing is set up for this deployment.
contactUrlstring
The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
creditsobject
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, almost at 80%, reached at 100% of available), 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).
enforcedbooleanRequired
Paid access is enforced for this organization.
enterpriseobject or null
An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (monthly; an older contract may be yearly or quarterly), 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 answers 402 plan_limit with reason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions.
guestsintegerRequired
Guests now: free.
hasCustomerboolean
A Stripe customer exists (the portal opens).
includedUsagestringRequired
Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoicesarray of objectsRequired
Recent invoices.
limitsobjectRequired
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_storage on Business and Enterprise; sso_scim, invoicing, sla, creative_memory on Enterprise), support.
membersintegerRequired
Members now: paid.
nextInvoiceobject or null
amount, currency, date.
organizationobjectRequired
id, name, workspaces [{id, name}], enterprise.
planobject or null
key (pro, business, enterprise) and name while subscribed; null during the free trial and without a plan.
plansarray of objectsRequired
Pro, Business and Enterprise with this organization's numbers.
ratesobjectRequired
currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnlyobject or null
since: read-only since then, until the organization subscribes; nothing is deleted.
recommendationobjectRequired
What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (pro or business, the one plans[].recommended marks, 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)}.
salesUrlstring
Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
sourcestringRequired
Where access comes from.One of subscription, trial, complimentary, none
statusstringRequired
The Stripe subscription's status.One of none, trialing, active, past_due, unpaid, canceled, incomplete, incomplete_expired, paused
storageobjectRequired
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).
subscriptionobject or null
plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
supportstring
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 of email, priority_email, shared_channel
syncedAtstring (date-time) or null
trialobject or null
startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailableboolean
Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspacesobjectRequired
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 included adds: 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-After seconds. 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"
POST/organizations/{id}/billing/plan/preview

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe 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

cadencestring
The billing period; the current one by default.One of monthly, yearly
planstringRequired
The plan.One of pro, business

Response200 OK

cadencestringRequired
The billing period.
dueTodayobjectRequired
dueToday.amountstringRequired
Decimal in the currency's major unit.
dueToday.currencystringRequired
ISO 4217, lower case.
effectivestringRequired
When it applies.One of now, period_end
expiresAtstring (date-time)Required
Until when it can be confirmed.
nextobjectRequired
next.amountstringRequired
Decimal in the currency's major unit.
next.currencystringRequired
ISO 4217, lower case.
next.intervalstringRequired
How often it bills.One of month, year
next.startsAtstring (date-time)
When the next period starts.
planstringRequired
The plan.
previewIdstring (uuid)Required
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-After seconds. 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"
  }'
POST/organizations/{id}/billing/portal

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe 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

flowstring
Where it opens; manage by default.One of manage, payment_method, cancel

Response201 Created

urlstringRequired
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-After seconds. 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"
  }'
PUT/organizations/{id}/billing/storage

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

enabledbooleanRequired
Extra storage on or off.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
limitstring or null
USD per month, such as 13.00; null is no limit.

Response200 OK

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.
  • 402plan_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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
POST/organizations/{id}/billing/sync

Refresh billing

Fetches the subscription and invoices from Stripe now and returns the same body as GET /organizations/{id}/billing.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accessstringRequired
What the organization may do now; none is read-only.One of full, grace, none
accessReasonstringRequired
Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntilstring (date-time) or null
adAccountsobjectRequired
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.
adAccountsByPlatformobjectRequired
Connected ad accounts per platform, each once across the organization's workspaces ({"meta": 2}): only platforms with at least one.
billingUrlstringRequired
The billing page in the app.
catalogueobjectRequired
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}.
configuredbooleanRequired
Billing is set up for this deployment.
contactUrlstring
The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
creditsobject
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, almost at 80%, reached at 100% of available), 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).
enforcedbooleanRequired
Paid access is enforced for this organization.
enterpriseobject or null
An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (monthly; an older contract may be yearly or quarterly), 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 answers 402 plan_limit with reason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions.
guestsintegerRequired
Guests now: free.
hasCustomerboolean
A Stripe customer exists (the portal opens).
includedUsagestringRequired
Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoicesarray of objectsRequired
Recent invoices.
limitsobjectRequired
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_storage on Business and Enterprise; sso_scim, invoicing, sla, creative_memory on Enterprise), support.
membersintegerRequired
Members now: paid.
nextInvoiceobject or null
amount, currency, date.
organizationobjectRequired
id, name, workspaces [{id, name}], enterprise.
planobject or null
key (pro, business, enterprise) and name while subscribed; null during the free trial and without a plan.
plansarray of objectsRequired
Pro, Business and Enterprise with this organization's numbers.
ratesobjectRequired
currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnlyobject or null
since: read-only since then, until the organization subscribes; nothing is deleted.
recommendationobjectRequired
What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (pro or business, the one plans[].recommended marks, 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)}.
salesUrlstring
Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
sourcestringRequired
Where access comes from.One of subscription, trial, complimentary, none
statusstringRequired
The Stripe subscription's status.One of none, trialing, active, past_due, unpaid, canceled, incomplete, incomplete_expired, paused
storageobjectRequired
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).
subscriptionobject or null
plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
supportstring
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 of email, priority_email, shared_channel
syncedAtstring (date-time) or null
trialobject or null
startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailableboolean
Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspacesobjectRequired
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 included adds: 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-After seconds. 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"
POST/organizations/{id}/billing/tax-ids

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe 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

typestringRequired
Stripe's tax ID type, such as eu_vat, gb_vat, no_vat, ch_vat, au_abn, ca_gst_hst.
valuestringRequired
The tax ID.

Response201 Created

addressobjectRequired
line1, line2, city, postalCode, state, country.
emailstring or null
Receives invoices and receipts.
namestring or null
The business name on invoices.
paymentTermsstringRequired
card: charged automatically; net_30: invoices are sent and due in 30 days (Enterprise).One of card, net_30
poNumberstring or null
Enterprise: the purchase order number printed on every invoice.
taxExemptstringRequired
Stripe's tax exemption.One of none, exempt, reverse
taxIdsarray of objectsRequired
Tax IDs.
taxStatusstringRequired
Whether tax can be calculated from the address (address_needed: add or complete it).One of ready, 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-After seconds. 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"
  }'
DELETE/organizations/{id}/billing/tax-ids/{tax_id}

Remove a tax ID

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
tax_idpathstringRequiredThe tax's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

addressobjectRequired
line1, line2, city, postalCode, state, country.
emailstring or null
Receives invoices and receipts.
namestring or null
The business name on invoices.
paymentTermsstringRequired
card: charged automatically; net_30: invoices are sent and due in 30 days (Enterprise).One of card, net_30
poNumberstring or null
Enterprise: the purchase order number printed on every invoice.
taxExemptstringRequired
Stripe's tax exemption.One of none, exempt, reverse
taxIdsarray of objectsRequired
Tax IDs.
taxStatusstringRequired
Whether tax can be calculated from the address (address_needed: add or complete it).One of ready, 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-After seconds. 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"
POST/organizations/{id}/billing/trial

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accessstringRequired
What the organization may do now; none is read-only.One of full, grace, none
accessReasonstringRequired
Why: trial, active, past_due, trial_ended, canceled, no_subscription, …
accessUntilstring (date-time) or null
adAccountsobjectRequired
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.
adAccountsByPlatformobjectRequired
Connected ad accounts per platform, each once across the organization's workspaces ({"meta": 2}): only platforms with at least one.
billingUrlstringRequired
The billing page in the app.
catalogueobjectRequired
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}.
configuredbooleanRequired
Billing is set up for this deployment.
contactUrlstring
The contact page: send the Pluto Ads team a message (sales, support, partnerships, press).
creditsobject
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, almost at 80%, reached at 100% of available), 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).
enforcedbooleanRequired
Paid access is enforced for this organization.
enterpriseobject or null
An Enterprise contract: contract {startsAt, endsAt (the commitment end), termYears, year, yearStartsAt, yearEndsAt, billing (monthly; an older contract may be yearly or quarterly), 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 answers 402 plan_limit with reason: agreement_full: add more with POST /organizations/{id}/billing/enterprise/additions.
guestsintegerRequired
Guests now: free.
hasCustomerboolean
A Stripe customer exists (the portal opens).
includedUsagestringRequired
Agent usage included this month (USD), pooled; unused credits roll over for 12 months.
invoicesarray of objectsRequired
Recent invoices.
limitsobjectRequired
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_storage on Business and Enterprise; sso_scim, invoicing, sla, creative_memory on Enterprise), support.
membersintegerRequired
Members now: paid.
nextInvoiceobject or null
amount, currency, date.
organizationobjectRequired
id, name, workspaces [{id, name}], enterprise.
planobject or null
key (pro, business, enterprise) and name while subscribed; null during the free trial and without a plan.
plansarray of objectsRequired
Pro, Business and Enterprise with this organization's numbers.
ratesobjectRequired
currency and models [{model, name, provider, providerName, input, cacheWrite, cacheRead, output, …}]: usage rates per million tokens.
readOnlyobject or null
since: read-only since then, until the organization subscribes; nothing is deleted.
recommendationobjectRequired
What the plan picker recommends for this team at each billing period, monthly and yearly, each {plan (pro or business, the one plans[].recommended marks, 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)}.
salesUrlstring
Talk to sales: the sales booking page (Enterprise, agreed limits, custom pricing).
sourcestringRequired
Where access comes from.One of subscription, trial, complimentary, none
statusstringRequired
The Stripe subscription's status.One of none, trialing, active, past_due, unpaid, canceled, incomplete, incomplete_expired, paused
storageobjectRequired
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).
subscriptionobject or null
plan, cadence, amount per period (decimal string), currency, billedMembers, currentPeriodStart/End, cancelAtPeriodEnd, canceledAt, scheduledPlan, scheduledAt.
supportstring
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 of email, priority_email, shared_channel
syncedAtstring (date-time) or null
trialobject or null
startedAt, endsAt, daysLeft, usageCap, workspaces.
trialAvailableboolean
Without a plan: the free trial can start (POST /organizations/{id}/billing/trial).
workspacesobjectRequired
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 included adds: 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-After seconds. 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/organizations/{id}/billing/workspace-costs

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.

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
periodquerystringOptionalcurrent (default), previous, or a billing period's id from cycles.
fromquerystringOptionalA UTC date range instead of period: first day, YYYY-MM-DD.
toquerystringOptionalLast day, YYYY-MM-DD (inclusive; at most 400 days after from).
invoicequerystringOptionalOne invoice's statement instead of a period: an invoice id (in_…) from the billing overview's invoices.
formatquerystringOptionaljson (default) or csv.
bomquerystringOptionaltrue 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

currencystringRequired
usd.
cyclesarray of objectsRequired
The organization's billing periods, newest first.
invoicedstring or nullRequired
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.total equals it once the period's storage is metered. For an invoice: its total before tax.
itemsarray of objectsRequired
One row per workspace, oldest first, then Shared.
organizationIdstringRequired
Organization ID.
periodobjectRequired
id (pass as period; null for a date range or an invoice), start, end.
planstring or nullRequired
pro, business or enterprise; null during the trial and without a plan.
totalsobjectRequired
fee, aiIncluded, storage, total.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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-After seconds. 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/organizations/{id}/usage

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
periodquerystringOptionalcurrent (default) or previous.
workspaceIdquerystringOptionalOnly this workspace (Business; 402 plan_limit on other plans).
agentIdquerystringOptionalOnly 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).
userIdquerystringOptionalOnly this member (owners and admins).
sourcequerystringOptionalhuman, agent, loop, api_mcp or creative_memory.
loopIdquerystringOptionalOnly this loop.
modelquerystringOptionalOnly this model.
qquerystringOptionalSearch members, sources, models and workspaces.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

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-After seconds. 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/organizations/{id}/usage/breakdown

Get a usage breakdown

Break usage down.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
byquerystringOptionalmember (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).
periodquerystringOptionalcurrent (default) or previous.
workspaceIdquerystringOptionalOnly this workspace (Business).
userIdquerystringOptionalOnly this member (owners and admins).
sourcequerystringOptionalhuman, agent, loop, api_mcp or creative_memory.
loopIdquerystringOptionalOnly this loop.
agentIdquerystringOptionalOnly this connected agent (Business).
modelquerystringOptionalOnly this model.
qquerystringOptionalSearch.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

bystringRequired
The breakdown.
itemsarray of objectsRequired
Largest first.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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-After seconds. 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"
GET/organizations/{id}/usage/export

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
periodquerystringOptionalcurrent (default) or previous.
workspaceIdquerystringOptionalOnly this workspace (Business; 402 plan_limit on other plans).
agentIdquerystringOptionalOnly 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).
userIdquerystringOptionalOnly this member (owners and admins).
sourcequerystringOptionalhuman, agent, loop, api_mcp or creative_memory.
loopIdquerystringOptionalOnly this loop.
modelquerystringOptionalOnly this model.
qquerystringOptionalSearch members, sources, models and workspaces.
bomquerystringOptionaltrue 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-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

CSV (text/csv).

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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-After seconds. 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"
POST/organizations/{id}/usage/exports

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).

Permission: readCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

agentIdstring
Only this connected agent: its credential's ID.
bomboolean
Start the file with a UTF-8 byte order mark, for a person opening it in a spreadsheet.
fromstring
A UTC date range instead of period: first day, YYYY-MM-DD.
gzipboolean
Compress the file with gzip (.csv.gz).
loopIdstring
Only this loop.
modelstring
Only this model.
periodstring
Billing period; current by default.One of current, previous
qstring
Search members, sources, models and workspaces.
sourcestring
Only this source.One of human, agent, loop, api_mcp, creative_memory
tostring
Last day, YYYY-MM-DD (inclusive).
userIdstring (uuid)
Only this member (owners and admins).
workspaceIdstring (uuid)
Only this workspace (Business).

Response202 Accepted

bombooleanRequired
The file starts with a UTF-8 byte order mark, so a spreadsheet reads accented and non-Latin letters correctly.
bytesinteger or nullRequired
The file's size, once written.
createdAtstring (date-time)Required
When it was asked for.
downloadUrlstring or nullRequired
A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReadybooleanRequired
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.
errorstring or nullRequired
Why it failed.
expiredbooleanRequired
Past expiresAt: the file is gone.
expiresAtstring (date-time) or nullRequired
When downloads end: 7 days after it was written.
fileNamestringRequired
The file's name.
filtersobjectRequired
What it applies, as checked.
finishedAtstring (date-time) or nullRequired
When it was written, or failed.
gzipbooleanRequired
The file is gzipped (.csv.gz).
idstring (uuid)Required
The export.
jobIdstring (uuid) or nullRequired
The job that writes it: follow it with GET /jobs/{id} (MCP wait_for_job).
kindstringRequired
What it holds: the audit log, a workspace's launches, ad sets and ads, or usage events.One of audit_log, workspace, usage
organizationIdstring (uuid) or nullRequired
The organization it's of; null for a workspace's audit log.
rowsTotalinteger or nullRequired
The rows it holds, once counted (null before); the file's own count once it's written.
rowsWrittenintegerRequired
The rows in the file so far.
statusstringRequired
done: the file is written and can be downloaded until expiresAt.One of queued, running, done, failed
workspaceIdstring (uuid) or nullRequired
The workspace a workspace export is of; null for other kinds.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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.
  • 409conflict: asked from a workspace that isn't an active one of the organization, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/organizations/{id}/usage/limits

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).

Permission: organization

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

loopsarray of objectsRequired
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.
membersarray of objectsRequired
Each member's monthly limit.
organizationIdstring (uuid)Required
The organization.
periodobjectRequired
start, end.
workspaceLimitsbooleanRequired
Whether the plan applies workspace limits (Business and up). Without it, workspaces still lists limits kept from Business: they don't apply, and each can be removed.
workspacesarray of objectsRequired
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-After seconds. 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"
PUT/organizations/{id}/usage/limits/loops/{loop_id}

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
loop_idpathstringRequiredThe loop's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

creditsinteger or nullRequired
Whole credits per billing period; null removes the cap.
versioninteger
The cap's version from GET /organizations/{id}/usage/limits (0 without one); leave out to overwrite.

Response200 OK

loopsarray of objectsRequired
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.
membersarray of objectsRequired
Each member's monthly limit.
organizationIdstring (uuid)Required
The organization.
periodobjectRequired
start, end.
workspaceLimitsbooleanRequired
Whether the plan applies workspace limits (Business and up). Without it, workspaces still lists limits kept from Business: they don't apply, and each can be removed.
workspacesarray of objectsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
PUT/organizations/{id}/usage/limits/members/{user_id}

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
user_idpathstringRequiredThe user's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
limitstring or nullRequired
USD per month, such as 100.00; null removes it.

Response200 OK

loopsarray of objectsRequired
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.
membersarray of objectsRequired
Each member's monthly limit.
organizationIdstring (uuid)Required
The organization.
periodobjectRequired
start, end.
workspaceLimitsbooleanRequired
Whether the plan applies workspace limits (Business and up). Without it, workspaces still lists limits kept from Business: they don't apply, and each can be removed.
workspacesarray of objectsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
PUT/organizations/{id}/usage/limits/workspaces/{workspace_id}

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.

Permission: organizationCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
workspace_idpathstringRequiredThe workspace's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
limitstring or nullRequired
USD per month, such as 100.00; null removes it.

Response200 OK

loopsarray of objectsRequired
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.
membersarray of objectsRequired
Each member's monthly limit.
organizationIdstring (uuid)Required
The organization.
periodobjectRequired
start, end.
workspaceLimitsbooleanRequired
Whether the plan applies workspace limits (Business and up). Without it, workspaces still lists limits kept from Business: they don't apply, and each can be removed.
workspacesarray of objectsRequired
Each workspace's monthly limit.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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"
  }'
GET/organizations/{id}/usage/records

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).

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
afterquerystringOptionalCursor from the previous page.
limitquerystringOptional1 to 500; 50 by default.
periodquerystringOptionalcurrent (default) or previous.
workspaceIdquerystringOptionalOnly this workspace (Business).
userIdquerystringOptionalOnly this member (owners and admins).
sourcequerystringOptionalhuman, agent, loop, api_mcp or creative_memory.
loopIdquerystringOptionalOnly this loop.
agentIdquerystringOptionalOnly this connected agent (Business).
modelquerystringOptionalOnly this model.
qquerystringOptionalSearch.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
nextAfterstring or nullRequired

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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-After seconds. 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"
POST/organizations/{id}/sales-leads

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.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe organization's ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

emailstringRequired
A work email to answer.
membersinteger
How many members, roughly.
messagestring or null
What they need, up to 5,000 characters.
namestringRequired
Who to answer, 1-200 characters.
organizationstringRequired
The company's name, 1-200 characters.
workspacesinteger
How many workspaces, roughly.

Response201 Created

createdAtstring (date-time)Required
When it was sent.
idstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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
  }'
GET/billing/rates

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.

No credential

Response200 OK

currencystringRequired
usd
modelsarray of objectsRequired
Models.

Errors

  • 400The request is malformed.
curl "$PLUTO_API/billing/rates"
GET/workspace/usage

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.

Permission: read

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adminbooleanRequired
An organization owner or admin: may set the workspace's limit.
limitstring or nullRequired
The workspace's monthly limit (USD); null: none.
limitVersionintegerRequired
Pass as expectedVersion when setting the limit.
membersarray of objectsRequired
Usage per person, highest first.
members[].amountstringRequired
USD this period.
members[].idstring or null
User ID.
members[].namestringRequired
Name.
organizationobjectRequired
organization.idstringRequired
Organization ID.
organization.namestringRequired
Name.
periodobjectRequired
period.endstringRequired
RFC 3339.
period.startstringRequired
RFC 3339.
scopestringRequired
workspace or own.
storageBytesintegerRequired
The same in exact bytes (1 GB = 1,073,741,824 bytes, as storage is metered).
storageGbstringRequired
This workspace's stored media, decimal GB (2 decimals).
usedstringRequired
USD this period, in scope.
workspaceobjectRequired
workspace.idstringRequired
Workspace ID.
workspace.namestringRequired
Name.
workspaceUsedstring or nullRequired
Admins: the workspace's usage against its limit.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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-After seconds. 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"