> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Top up the balance, and see the usage

> Top up the balance of a workspace, turn on automatic top-up, set a monthly spending limit, and see the cost of each sandbox and each label. Read the usage with the API.

Usage takes the plan credit first, then the prepaid balance. Use **Billing** to add money to the balance, to top it up on its own, to set a spending limit, and to see what each sandbox costs.

Set up the balance of my workspace.

Ask how much my sandboxes cost each month.
Suggest a top-up amount with a bonus from the plans reference, and a limit for automatic top-up.
Tell me how to set a monthly spending limit.

## Before you start

* You need the **Owner** or **Admin** role to top up, to change automatic top-up, and to change the spending limit. Each member can see the balance and the usage. See [roles](https://vms.dev/docs/reference/plans.md#roles).
* Top-ups also work during the trial.

## What the Billing page shows

To open the page, choose **Settings** in the rail, then **Billing**. These cards show the usage and the money:

| Card | Shows |
| - | - |
| **Overview** | **Total spend this month**: the cost of the usage since the first day of the month (UTC). |
| **Balances** | **Credit** from the plan or the trial, and **Balance** from top-ups and bonuses. **Breakdown and expiration** shows the top-ups, the bonuses, and each credit with its expiry date. |
| **Automatic top-up** | The limit and the amount of automatic top-up. |
| **One-time top-up** | Four amounts and a custom amount, with the bonus. With a saved card, **Top up** charges the default card. |
| **Spending limit** | The most that the workspace can spend on usage each month. |
| **Usage this month** | The cost of each sandbox this month. Deleted sandboxes are on one row. |
| **Cost by label** | The cost of each label this month. |

## Top up the balance

1. In the rail, choose **Settings**, then **Billing**.
2. In **One-time top-up**, choose an amount, or type a custom amount from $5 to $100,000. The card shows the bonus.
3. Choose **Top up**.
4. If the workspace has a saved card, a dialog shows the amount and the card, such as **Charge \$100.00 to Visa •••• 4242?** Choose **Charge**. The default card pays. If the workspace has no default card, the newest card pays.
5. If the workspace has no saved card, the Stripe page opens. Enter your card and confirm. Stripe saves the card for the next top-ups and sends you back to **Billing**.

![The One-time top-up card with the amounts \$25, \$100, \$500, and \$1,000, a custom amount field, and the Top up button.](https://mintcdn.com/vms-c6f4e5ac/kvsBm-leIVQYZQAw/images/workspace/billing/02-one-time-top-up-light.png?fit=max\&auto=format\&n=kvsBm-leIVQYZQAw\&q=85\&s=66f91c83e240e729973b13484fd0bb57)

**Balances** and **Charges** show the top-up and its bonus after Stripe reports the payment as paid. Stripe sends a receipt for each top-up. See the [bonus of each amount](https://vms.dev/docs/reference/plans.md#top-ups).

If your bank asks you to confirm the payment, its page opens. Confirm the payment there. The bank sends you back to **Billing**, and **Balances** shows the top-up.

If the bank declines the card, the dialog shows the error, and the balance does not change. To use a different card, choose **Edit** in **Payment methods**, add the card, and make it the default card. Then top up again.

## Turn on automatic top-up

1. In the rail, choose **Settings**, then **Billing**.
2. In **Automatic top-up**, type the limit in **When the funds go below**, and the amount in **Top up by**. The amount must be \$5 or more.
3. Choose **Save**.

When the credit and the balance together go below the limit, your cards pay the amount, with its bonus. The default card pays first. If it declines, the next card pays.

After 3 declined top-ups in a row, automatic top-up turns off, and the owners and admins get an email. Add a card, then choose **Save** again. To stop automatic top-up, choose **Turn off**.

## Set a spending limit

1. In the rail, choose **Settings**, then **Billing**.
2. In **Spending limit**, type the limit for each month.
3. Choose **Save**.

The owners and admins get an email when the usage of the month reaches 50%, 80%, and 100% of the limit. At 100%, the running sandboxes stop with their data kept, and a create or a resume answers `402 billing_required` until the next month or until you raise the limit. To remove the limit, choose **Remove**.

## Cap the use of each member

**Member caps** shows the running sandboxes and the unit-hours of this month for each member.

1. In **Member caps**, choose the row of the member.
2. Type the most sandboxes at the same time, and the most unit-hours each month. Leave a field empty for no cap.
3. Choose **Save**.

A start above a cap answers `429 start_limit`. The sandboxes of an API key count for the person who created the key. To remove the caps of more than one member, select their rows, choose **Actions**, then **Remove caps**.

## See the cost of each sandbox

**Usage this month** shows the cost of each sandbox since the first day of the month (UTC). **Cost by label** shows the cost of each label. A sandbox with two labels counts in both rows.

To download the usage of each hour of the month, choose **Export CSV** in **Usage this month**. The file has the columns `hour_start`, `unit_seconds`, and `cost_usd`.

## Read the usage with the API

[`GET /v1/usage`](https://vms.dev/docs/api-reference/billing/get-the-usage) returns the usage of each minute, hour, or day in a window, with the credit and the balance. It needs the `billing:read` scope. Amounts are in micro-dollars: 1,000,000 is \$1.

```typescript TypeScript theme={null}
const query = new URLSearchParams({
  from: "2026-11-16T00:00:00Z",
  to: "2026-11-16T12:00:00Z",
  granularity: "hour",
});

const response = await fetch(`https://vms.dev/api/v1/usage?${query}`, {
  headers: { authorization: `Bearer ${process.env.VMS_API_KEY}` },
});

const usage = await response.json();

console.log(usage.costMicros, usage.funds.totalMicros);
```

```bash cURL theme={null}
curl "https://vms.dev/api/v1/usage?from=2026-11-16T00:00:00Z&to=2026-11-16T12:00:00Z&granularity=hour" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

The default window is the last 24 hours, by minute. A window can have 10,080 points or fewer.

To count only some sandboxes, add `label=key:value`. Send it more than one time for more labels. A sandbox must have each label. To get the cost of each value of a label, add `groupByLabel=<key>`. The answer then has `groups`, with the highest cost first. For example, `label=env:prod&groupByLabel=customer` gives the cost of each customer in production. A sandbox without the label is in the group with `value: null`.

To get the cost of one sandbox for any window, call [`GET /v1/sandboxes/{id}/usage`](https://vms.dev/docs/api-reference/sandboxes/get-the-usage-of-a-sandbox) with `from` and `to`. The default window is the current month. To get the cost of each sandbox this month in a list, add `include=cost` to [`GET /v1/sandboxes`](https://vms.dev/docs/sandboxes/list-and-label#list-the-cost-of-each-sandbox). These two endpoints need the `sandboxes:read` scope.

## When the credit and the balance are empty

With a paid plan, the workspace keeps running for 48 hours, and its balance can go below zero to the debt allowance. **Balances** shows the date when the sandboxes stop. After 48 hours, or at the debt allowance, the sandboxes stop with their data kept, and a create or a resume answers `402 billing_required`.

Top up the balance to start them again. See [grace and debt](https://vms.dev/docs/reference/plans.md#grace-and-debt).

In the trial, or without a plan, the sandboxes stop when the credit and the balance are empty.

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.