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.
Add credits
An amount from $20 to $10,000 (dollars and cents), with an idempotency key that names the top-up:- Ask your agent
- See the code
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 headerIdempotent-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 is200, with one of four statuses. Over HTTP, a top-up that went through answers:
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.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:
This key or sign-in does not have the billing permission. An owner or manager turns it on (see above).
This top-up would pass a cap.
details has cap (daily, monthly or new_workspace), cap_usd, spent_usd, remaining_usd and resets_at.Card payments for this workspace are paused while a card dispute is open. A person pays by bank transfer in the dashboard instead.
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.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.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: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:
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
- MCP
- CLI
- TypeScript
- Python
The MCP server has no tool for payment methods.