Credits
How your subscription covers every workspace, and how to move AI credits to a workspace, read its balance and usage, and top it up automatically.
You pay for everything. Your customers' workspaces have no plan and no payment method of their own.
The pool model
Two things are shared between your own workspace and all your customer workspaces:
- Agents. Your plan plus your agent seats is one pool. Every agent in every
workspace counts against it.
GET /accountshowspool.agentsandpool.agentsLimit. When the pool is full, creating an agent answers 402plan_limit. Buy agent seats in the dashboard's Billing page to grow it. - Your subscription. While it is active, every call works. See When a payment fails for the other states.
AI credits are not shared. Each workspace has its own balance, and an agent spends the balance of its own workspace on model calls, memory and connected apps.
- A new workspace starts at zero. It gets no free credits and no monthly refill.
- Its credits come only from you: you move credits from your account to the workspace, by hand or with an automatic top-up.
- Only your purchased credits can move. The monthly credits included in
your plan stay in your own workspace.
GET /accountshows three numbers incredits:balanceCentsis both together,purchasedCentsis the purchased part, andtransferableCentsis what a transfer can move. ReadtransferableCentsbefore a transfer: a larger amount answers 402insufficient_pool, also whenbalanceCentslooks high enough. Buy credits in the dashboard's Billing page. - An agent cannot be created in a workspace with no credits, and a message to
an agent in a workspace with no credits answers 402
credits_exhausted.
All amounts are cents of credit: 2500 is $25.00.
When a payment fails
A payment is past due. Your agents keep running, and your end users keep
their service. What grows your use is refused with 402 billing_inactive
until the payment succeeds:
Refused with 402 billing_inactive | Keeps working |
|---|---|
| Create a workspace | Messages, turns and event streams |
| Create an agent, explicit or from a recipe | Schedules |
The resume and redeploy actions | App connections |
| Upgrade an agent | Memory calls |
| Start a recipe test run | Skill and MCP server changes |
| Move credits | Agent updates and instruction changes, the suspend action |
| Change the automatic top-up | Every read and every delete |
An automatic top-up moves no credits while a payment is past due. A workspace then runs on the balance it has.
The subscription is canceled or paused. The agents of every workspace are suspended, so no message is answered. Reads and deletes still work. When the subscription is active again, the agents that this stop suspended start again.
Move credits to a workspace
POST /workspaces/{workspaceId}/credits| Field | Type | Rules |
|---|---|---|
amountCents | integer | Required. 100 to 1,000,000 ($1.00 to $10,000.00). |
requestId | string | Required. A UUID you generate. It makes the transfer safe to retry. |
reason | string | Optional. 1 to 200 characters, for your own records. |
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/credits \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{
"amountCents": 2000,
"requestId": "0b6f2d1e-7c3a-4e58-9a41-5d2c8e7f1a90",
"reason": "November allowance"
}'{
"requestId": "0b6f2d1e-7c3a-4e58-9a41-5d2c8e7f1a90",
"amountCents": 2000,
"balanceCents": 3840,
"createdAt": "2026-11-20T09:15:11.640Z"
}balanceCents is the workspace's balance after the transfer.
The answer is 201 for a new transfer. Send the same requestId with the
same amount to the same workspace, and you get 200 with the first transfer:
no credits move twice. The same requestId with another amount or another
workspace answers 409 conflict. Generate a new requestId for each transfer
you intend, and reuse it only to retry.
Credits move in one direction. To get unspent credits back, delete the workspace.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A field breaks a rule above. |
| 402 | billing_inactive | Your subscription is not active, or a payment is past due. |
| 402 | insufficient_pool | Your purchased credits are lower than amountCents. |
| 404 | not_found | No such workspace in your account. |
| 409 | conflict | This requestId was used with other values. |
| 409 | workspace_deleting | The workspace is being deleted. |
| 503 | unavailable | The credits could not be moved at that moment. Nothing moved: send the same request again. |
A transfer first books what your own workspace has spent, so only credits you
have not used can move. If the answer is lost, send the same requestId again:
a replay also finishes a transfer whose last step did not complete.
Read the balance
GET /workspaces/{workspaceId}/creditscurl https://sokko.ai/api/v1/workspaces/$WORKSPACE/credits \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{
"balanceCents": 3712,
"keyProvisioned": true,
"autoTopUp": {
"thresholdCents": 500,
"amountCents": 2000,
"monthlyCapCents": 10000,
"monthTotalCents": 4000
}
}| Field | Meaning |
|---|---|
balanceCents | The balance now. This call brings it up to date with the latest spend before it answers. |
keyProvisioned | false until the workspace gets its first credits. Its agents cannot call a model before that. |
autoTopUp | The automatic top-up settings, or null when it is off. monthTotalCents is this month's total. |
The credits.balanceCents of a workspace object is the stored number, which
can be a few minutes old. This call is the fresh one.
Errors: 404 not_found.
Read usage per day
GET /workspaces/{workspaceId}/usage| Query | Meaning |
|---|---|
from | First day, YYYY-MM-DD, UTC. Default: 29 days before to. |
to | Last day, YYYY-MM-DD, UTC, included. Default: today. |
A range holds at most 92 days.
curl "https://sokko.ai/api/v1/workspaces/$WORKSPACE/usage?from=2026-11-18&to=2026-11-20" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{
"days": [
{ "day": "2026-11-18", "modelsCents": 41, "memoryCents": 3, "appsCents": 0 },
{ "day": "2026-11-19", "modelsCents": 67, "memoryCents": 5, "appsCents": 2 },
{ "day": "2026-11-20", "modelsCents": 9, "memoryCents": 1, "appsCents": 0 }
],
"totalCents": 128
}Every day of the range has a row, oldest first, also a day with no spend.
modelsCents: what the agents' model calls cost. Spend is booked within minutes, so a call just before midnight UTC can land on the next day.memoryCents: what the shared memory cost.appsCents: what connected-app actions cost.
Errors: 400 invalid_request (a date that is not YYYY-MM-DD, from after
to, or more than 92 days), 404 not_found.
Automatic top-up
With a top-up, the platform moves credits for you when a workspace runs low, up to a cap per calendar month.
PUT /workspaces/{workspaceId}/credits/auto-top-up| Field | Type | Rules |
|---|---|---|
thresholdCents | integer | 1 to 1,000,000. A top-up runs when the balance is below this. |
amountCents | integer | 100 to 1,000,000. What one top-up moves. |
monthlyCapCents | integer | 1 to 10,000,000, and at least amountCents. The most one month can move. |
curl -X PUT https://sokko.ai/api/v1/workspaces/$WORKSPACE/credits/auto-top-up \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "thresholdCents": 500, "amountCents": 2000, "monthlyCapCents": 10000 }'{
"autoTopUp": {
"thresholdCents": 500,
"amountCents": 2000,
"monthlyCapCents": 10000,
"monthTotalCents": 0
}
}To turn the top-up off, send the JSON value null as the body:
curl -X PUT https://sokko.ai/api/v1/workspaces/$WORKSPACE/credits/auto-top-up \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d 'null'{ "autoTopUp": null }How it runs
- The platform checks each workspace with settings every few minutes. It also
checks when a message arrives for a workspace that has no credits left, so
that message is not refused if a top-up is possible. A workspace that stays
empty gets one such check per minute: the messages in between answer 402
credits_exhaustedat once. - A top-up moves
amountCentsfrom your purchased credits when the balance is belowthresholdCentsand this month's total plusamountCentsstays at or belowmonthlyCapCents. A month is a calendar month in UTC. - Each top-up sends the event
credits.topped_up. - When the cap stops a top-up, nothing moves, and the event
credits.cap_reachedis sent once for that month. The workspace then runs until its balance is zero. Raise the cap or move credits by hand. - When your purchased credits are too low, or your subscription is not active (a past-due payment included), nothing moves and no event is sent.
- New settings do not reset
monthTotalCents.
See Webhooks for the two events.
Errors: 400 invalid_request, 402 billing_inactive (your subscription is not
active, or a payment is past due), 404 not_found, 409 workspace_deleting.
When the credits run out
A message to a workspace with no credits answers 402 credits_exhausted
before a turn starts. If the credits run out while a turn runs, the model
call fails inside the agent. The turn then ends as failed with
credits_exhausted, or the agent answers with a fixed sentence that says its
AI credits are used up. That sentence names Sokko. Keep a balance above zero,
with an automatic top-up, so that your end users do not read it.