Sokko Docs
Platform API

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 /account shows pool.agents and pool.agentsLimit. When the pool is full, creating an agent answers 402 plan_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 /account shows three numbers in credits: balanceCents is both together, purchasedCents is the purchased part, and transferableCents is what a transfer can move. Read transferableCents before a transfer: a larger amount answers 402 insufficient_pool, also when balanceCents looks 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_inactiveKeeps working
Create a workspaceMessages, turns and event streams
Create an agent, explicit or from a recipeSchedules
The resume and redeploy actionsApp connections
Upgrade an agentMemory calls
Start a recipe test runSkill and MCP server changes
Move creditsAgent updates and instruction changes, the suspend action
Change the automatic top-upEvery 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
FieldTypeRules
amountCentsintegerRequired. 100 to 1,000,000 ($1.00 to $10,000.00).
requestIdstringRequired. A UUID you generate. It makes the transfer safe to retry.
reasonstringOptional. 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.

StatusCodeWhen
400invalid_requestA field breaks a rule above.
402billing_inactiveYour subscription is not active, or a payment is past due.
402insufficient_poolYour purchased credits are lower than amountCents.
404not_foundNo such workspace in your account.
409conflictThis requestId was used with other values.
409workspace_deletingThe workspace is being deleted.
503unavailableThe 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}/credits
curl 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
  }
}
FieldMeaning
balanceCentsThe balance now. This call brings it up to date with the latest spend before it answers.
keyProvisionedfalse until the workspace gets its first credits. Its agents cannot call a model before that.
autoTopUpThe 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
QueryMeaning
fromFirst day, YYYY-MM-DD, UTC. Default: 29 days before to.
toLast 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
FieldTypeRules
thresholdCentsinteger1 to 1,000,000. A top-up runs when the balance is below this.
amountCentsinteger100 to 1,000,000. What one top-up moves.
monthlyCapCentsinteger1 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_exhausted at once.
  • A top-up moves amountCents from your purchased credits when the balance is below thresholdCents and this month's total plus amountCents stays at or below monthlyCapCents. 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_reached is 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.

On this page