Skip to main content
A program or agent that runs long work can keep its own balance topped up: it reads how long the balance lasts, adds credits when it runs low, and manages auto-recharge. A top-up charges the workspace’s saved default card, the one a person added in the dashboard. Cards are never added or changed by API.

Turn on Top-ups

No key or agent sign-in can top up until a workspace owner or manager turns on its Top-ups (in the API, the billing permission):
1

Open API keys

Go to Dashboard > API keys.
2

Pick the key or sign-in

Open the menu of an API key, or of an agent sign-in (MCP or CLI) in the agent sign-ins list, and choose Top-ups.
3

Set the caps

Turn the permission on and set its daily and monthly caps (from $20; $100 a day and $500 a month to start). Save.
Each key or sign-in has its own caps. A day and a month are counted in UTC, and only money actually charged or being charged counts: declined and cancelled top-ups do not. Turning Top-ups off, or the person who turned them on leaving the owner or manager role, stops the key from charging at once; turning them off also turns off auto-recharge that key set. The workspace’s default key, inference-only keys and turned-off keys cannot get Top-ups.

Add credits

An amount from $20 to $10,000 (dollars and cents), with an idempotency key that names the top-up:
Connect the Runcrate MCP server, then ask in plain words:
The agent reads billing_balance and calls top_up with amount_usd: 50. The MCP server derives the idempotency key from the tool call, so a call its client retries never charges twice. On requires_action it gives you the confirm_url. See MCP tools.

Idempotency

The key names one top-up. Sending the same key again never charges twice: it answers the same top-up with its current status, with the header Idempotent-Replayed: true. That is also how you read a top-up later: re-send the same request. Use a new key for a new top-up; the same key with another amount is refused with 409 IDEMPOTENCY_KEY_REUSED. Use any 1 to 255 printable characters without spaces, such as a UUID made for each top-up. Keep the key until you know the outcome, and never retry with a new key after a timeout. Over HTTP the key may also go in an Idempotency-Key header; if you send both, they must match.

Statuses

Every answer is 200, with one of four statuses. Over HTTP, a top-up that went through answers:
The statuses:
Paid and credited. balance_usd is the new balance and invoice_number the invoice. Nothing to do.
The payment is going through and is not credited yet. Re-send the same request in a minute to read it, or wait for topup.succeeded.
The bank wants the card holder to confirm. Nothing is charged yet. A person opens confirm_url, signed in to Runcrate as an owner or manager of the workspace, and confirms before expires_at. Then re-send the same request to read the result.
Nothing was charged. reason (card_declined, payment_blocked or authentication_required) and message say why. Tell a person: the default card may need replacing in Billing > Payment methods.
An agent that gets requires_action should give its user the confirm_url link; it cannot confirm the payment itself.

Errors

Errors use the usual envelope, { "error": { "code", "message", "details" } }, and charge nothing. The codes, each with its HTTP status:
403
This key or sign-in does not have the billing permission. An owner or manager turns it on (see above).
402
This top-up would pass a cap. details has cap (daily, monthly or new_workspace), cap_usd, spent_usd, remaining_usd and resets_at.
402
The workspace has no saved default card. A person adds one in the dashboard.
402
Card payments for this workspace are paused while a card dispute is open. A person pays by bank transfer in the dashboard instead.
402
Card payments for this workspace are stopped after repeated declined card attempts: for an hour the first time, for 24 hours the second time within 30 days, and until Runcrate lifts it after that. details has level (1, 2 or 3) and until (when card payments open again, or null until Runcrate lifts it). Don’t retry before until; a person pays by bank transfer in the dashboard instead, or writes to support@runcrate.ai.
409
The key was used for a top-up of another amount. Use a new key.
409
A top-up with this key, or another card payment of the workspace, is being charged right now. Re-send the same request after Retry-After seconds.
422
The amount or key is not valid.
429
Too many requests. Wait and re-send the same request.

Read the runway

GET /api/v1/billing/balance tells a program when to top up:

Auto-recharge by API

Read the workspace’s auto-recharge with any key or sign-in:
It answers enabled, threshold_usd, target_usd, and last_failure_reason and last_failure_at when the last automatic top-up failed. It also answers mode (fixed or keep_hours), keep_hours, monthly_cap_usd and charged_this_month_usd, burn_per_hour_usd (what the running instances cost), effective_threshold_usd and effective_target_usd (what the next check uses), soft_decline_at (a decline that may clear, retried once 10 minutes later), and notice: set when fixed amounts are small for that cost, with the numbers and what Keep 24 hours would set. Change it with PUT. This needs the billing permission, and the person behind the key or sign-in must be an owner or manager:
threshold_usd ($20 to $5,000) and target_usd ($50 to $10,000, above the threshold) are required, even to turn it off, as in the dashboard. A target_usd above the key’s daily cap is refused with 402 TOPUP_CAP_REACHED. Without a saved card, turning it on answers 402 NO_PAYMENT_METHOD. Turning it off is never refused for the cap. To keep hours of usage instead of fixed amounts, send mode keep_hours with a monthly_cap_usd ($50 to $500,000), and optionally keep_hours (4 to 168, default 24). The amounts then default to the saved ones and are the least it uses:
A PUT without mode keeps the saved mode; mode fixed goes back to fixed amounts. keep_hours or monthly_cap_usd sent without mode keep_hours is refused with 422 VALIDATION_ERROR, so a cap is never dropped silently. With keep hours (sent, or already saved), a recharge at the running instances’ cost now that is above the key’s daily cap is refused with 402 TOPUP_CAP_REACHED: choose fewer hours, or raise the cap. Auto-recharge turned on or changed by API counts against that key’s or sign-in’s caps, like its own top-ups: each recharge is cut down to what is left of today’s and this month’s cap, and skipped (nothing charged, auto-recharge stays on) when less than $20 is left. If the key loses the billing permission, or the person who granted it is no longer an owner or manager, auto-recharge turns off with last_failure_reason billing_permission_removed until a person saves it in the dashboard. Saving auto-recharge in the dashboard takes it off the key’s caps.

Payment methods

GET /api/v1/billing/payment-methods lists the saved cards (brand, last4, exp_month, exp_year, and which is the default), so a program can tell whether a top-up can work. It needs the billing permission, or a key of an owner or manager. The list is read only: cards are added, removed and made default only in the dashboard, in Billing > Payment methods.

Webhooks

Webhooks tell you how top-ups end, whatever started them:

MCP, CLI and SDKs

The MCP server has no tool for payment methods.
The MCP server, CLI and SDKs never retry a top-up with a new key.