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

# Billing

> Read credits, usage, and billing settings

Billing endpoints use:

```text theme={null}
https://billing.runtools.ai/v1
```

Billing endpoints are organization-admin surfaces unless noted otherwise. Usage is returned at the customer-facing resource level: model tokens, sandbox runtime, storage, tool executions, and credit balance. Platform-internal provider routing is not exposed.

## Plan And Credits

| Method | Path                          | Description                     |
| ------ | ----------------------------- | ------------------------------- |
| `GET`  | `/v1/billing/plan`            | Current plan and credit summary |
| `GET`  | `/v1/billing/credits`         | Current credit balance          |
| `GET`  | `/v1/billing/credits/history` | Credit ledger history           |

```bash cURL theme={null}
curl https://billing.runtools.ai/v1/billing/plan \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

## Usage

`GET /v1/billing/my-usage` returns usage for the authenticated admin by default. Pass `all=true` to include per-member rows for the organization.

<ParamField query="period" type="string" default="current">
  One of `current`, `7d`, `30d`, or `all_time`.
</ParamField>

<ParamField query="all" type="boolean">
  Admin-only: include all organization members and aggregate org totals.
</ParamField>

```bash cURL theme={null}
curl "https://billing.runtools.ai/v1/billing/my-usage?period=30d" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

```typescript SDK theme={null}
const usage = await rt.billing.myUsage({ period: '30d' });
const allOrg = await rt.billing.myUsage({ all: true, period: 'current' });
```

Usage rows include:

| Field             | Meaning                                                          |
| ----------------- | ---------------------------------------------------------------- |
| `tokens`          | Platform model input/output/total tokens                         |
| `modelUsage`      | Usage by model identifier, not by internal provider              |
| `sandboxRuntime`  | Settled, pending, forgiven, and active sandbox runtime estimates |
| `storageUsage`    | Workspace storage byte-second summaries                          |
| `toolExecutions`  | Tool execution count                                             |
| `resourceCharges` | Other settled resource-level charges                             |

BYOK model calls use customer-provided keys and are not charged as Platform inference.

## Top Up Credits

| Method | Path                             | Access    | Description                                        |
| ------ | -------------------------------- | --------- | -------------------------------------------------- |
| `POST` | `/v1/billing/topup`              | Org admin | Create a Stripe Checkout session for credit top-up |
| `GET`  | `/v1/billing/success`            | Org admin | Verify a completed checkout session                |
| `POST` | `/v1/billing/promo-codes/redeem` | Org admin | Redeem a promo code for credits                    |
| `GET`  | `/v1/billing/auto-topup`         | Org admin | Read auto-top-up settings                          |
| `PUT`  | `/v1/billing/auto-topup`         | Org admin | Update auto-top-up settings                        |

```bash cURL theme={null}
curl -X POST https://billing.runtools.ai/v1/billing/topup \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":2500}'
```

```bash cURL theme={null}
curl -X PUT https://billing.runtools.ai/v1/billing/auto-topup \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "thresholdCents": 1000,
    "topupAmountCents": 2500
  }'
```

## What Is Measured Automatically

RunTools measures Platform model tokens, sandbox runtime, workspace storage, and tool executions as they happen. BYOK model calls use your own provider credentials and are not charged as Platform inference.