# Billing

Prepaid credits in US dollars, metered by the second of completed audio, with no charge for failures — plus top-ups, automatic top-ups, and where to watch usage.

Sandchest is prepaid. You buy credits in US dollars, and transcription draws them
down by the second of audio it actually completed. No seats, no subscription, no
monthly minimum. This page covers how metering works, how to add credits, and where
to see what you have spent.

## Prepaid credits

Your workspace holds a US-dollar credit balance. Every completed transcript
subtracts the cost of its measured audio duration. When the balance runs out, new
transcription requests are refused:

```json title="402 Payment Required"
{ "error": "Your credit balance is exhausted. Add credits to continue transcribing." }
```

Existing transcripts keep processing — only new requests are held back. Add credits
and everything resumes at once.

The dashboard shows your current price per audio hour, formatted like
`$0.21 / audio hour`, alongside your balance.

## What gets metered

| | |
| --- | --- |
| Unit | One second of audio |
| Measured from | The decoded media duration, not the file size or the wall-clock time |
| Charged when | The transcript reaches `status: "completed"` |
| Not charged | Anything that ends in `status: "error"` |
| Not charged | Uploads, polling, listing, deletion, captions, sentences, paragraphs, word search |

Only the audio that finished counts. A transcript that fails during inference — an
unsupported language, undecodable media, a worker fault — costs nothing. Storage,
API calls and every derived resource are free; you pay for transcription.

`audio_start_from` and `audio_end_at` trim what is transcribed, and therefore what
is billed.

> [!NOTE]
> Metering is exactly-once. Each completed transcript produces one usage event,
> keyed by its transcript id, and a retry or a redelivery can never double-charge.

## Adding credits

Go to [sandchest.com/dashboard/billing](https://sandchest.com/dashboard/billing) and
choose an amount.

| | |
| --- | --- |
| Minimum | $5 |
| Maximum | $1,000 |
| Increments | Whole dollars only |

Anything outside that returns
`Choose a whole-dollar credit amount between $5 and $1,000.` Credits do not expire
and are not refundable to a card; they stay on the workspace.

Only a workspace **owner** can buy credits or change billing settings. Admins can
manage API keys and members; members can transcribe. See
[Authentication](/docs/authentication#workspaces-and-roles).

## Automatic top-ups

Turn on auto top-up and Sandchest buys more credits before you run dry.

| Setting | Rules |
| --- | --- |
| Threshold | A whole number of dollars, at least `$1` and **below** the top-up amount |
| Amount | The same $5–$1,000 whole-dollar range as a manual top-up |
| Monthly limit | Between 1 and 100 top-ups per month — a hard ceiling on spend |

Two prerequisites, each with its own message if you skip it:

- A saved payment method — `Add a payment method before enabling automatic top-ups.`
- At least one completed manual purchase — `Purchase credits once before enabling
  automatic top-ups.`

Turning auto top-up **off** never depends on any of that. Disabling it keeps your
stored settings and simply stops future charges, so you can always stop spending.

## Watching usage

[sandchest.com/dashboard/usage](https://sandchest.com/dashboard/usage) shows audio
hours transcribed and what they cost. The billing page shows your remaining balance,
plus anything already used but not yet reconciled with the payment provider — so the
number you see is what you can actually still spend, not an optimistic one.

Per transcript, `audio_duration` is the billable length in **seconds**:

```bash
curl -sS "https://stt-api.sandchest.com/v2/transcript?limit=100&status=completed" \
  -H "Authorization: $SANDCHEST_API_KEY" | jq '.transcripts | length'
```

## Self-hosting

There is no billing when you run Sandchest yourself. Set `SANDCHEST_SELF_HOSTED=true`
and the entitlement check is bypassed entirely — no credits, no metering, no payment
provider. Your costs are your own GPU, storage and bandwidth. See
[Self-hosting](/docs/self-hosting).

## Verify

Confirm your workspace can transcribe by creating a transcript. A `402` means you are
out of credits; anything else means billing is not what is blocking you.

```bash
curl -sS -o /dev/null -w '%{http_code}\n' https://stt-api.sandchest.com/v2/transcript \
  -H "Authorization: $SANDCHEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"'"$UPLOAD_URL"'"}'
```

```text title="expected output"
200
```

## Next

[Self-hosting](/docs/self-hosting) — run the whole thing on your own hardware.