---
title: Top up
description: How to add credit to a workspace, from the dashboard or with the top_up tool, and what the rate limits and error reasons mean.
sidebar:
  icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" class="looot-icon"><path class="li-i" d="M4 7.5A2.5 2.5 0 0 1 6.5 5H18v3"/><rect class="li-i" x="4" y="8" width="17" height="11" rx="2.5"/><circle class="li-af" cx="16.5" cy="13.5" r="1.6"/></svg>'
---

Top-ups are paid on Stripe's hosted Checkout page. looot never sees your card, and an agent never
enters card details.

## From the dashboard

Open [looot.ai/usage?top_up=1](https://looot.ai/usage?top_up=1), pick an amount, pay. This is the
one path a person uses directly; it is also the only way to start a session with a dashboard
owner or admin login.

## From an agent

An agent token cannot open a Stripe session directly. It gets a link instead:

<CodeGroup>

```json MCP
top_up { "amountUsd": 25 }
```

```bash CLI
looot balance
# read topUpLink.checkoutUrl or topUpLink.dashboardUrl from the output
```

</CodeGroup>

The [`top_up`](/mcp-tools/top-up) tool returns a Checkout link for the customer to open and pay on. `amountUsd` is
optional; without it, looot suggests an amount: at least the minimum, at least the shortfall
rounded up to the next $10, and at least five times what the run you are about to make would cost,
capped at the maximum. `GET /v1/balance` (and the [`balance`](/mcp-tools/balance) tool's `topUpLink`) also carries a
`checkoutUrl` once a session is open, so you do not always need to call `top_up` first.

## Reuse and rate limits

Asking again for the same amount within 10 minutes returns the same pending session. No new
one opens. A workspace can open at most 3 new sessions per hour. The minimum and maximum
are shown on the dashboard's form and in the `top_up` tool's answer.

## Errors

| Code | Meaning |
| --- | --- |
| [`top_up_amount_out_of_range`](/errors/mcp-errors#top_up_amount_out_of_range) | Below the minimum, or above the maximum. Call `top_up` with at least `minimumUsd`, or without an amount. |
| [`top_up_unavailable`](/errors/mcp-errors#top_up_unavailable) | No payment link for this workspace right now. Give the person the `dashboardUrl` from the answer. The reason can be `billing_disabled`, `operator_workspace`, `read_only_token`, [`rate_limited`](/errors/run-errors#rate_limited), `checkout_failed`, `stripe_timeout` or `balance_sufficient`. |

## After you top up

Credits land on your balance once Stripe confirms the payment, not the moment Checkout opens.
After paying, run the call again with a **new** idempotency key; the run refused for
[`insufficient_balance`](/errors/rest-errors#insufficient_balance) keeps its old key and is not automatically retried.

<Related />