# Usage and billing

See what a project uses, what it costs, and cap its spend and sessions.

The commands reuse `API`, `MOQ_API_TOKEN`, and `PID` from the [quickstart](/quickstart). The project's **Billing** and **Cost** pages show the same numbers.

## What is metered

Usage is metered per project in these fields, which the usage API returns. Publishing in is free.

| Field | What it counts |
| --- | --- |
| `egressExternalBytes` | Live media delivered to viewers, over any protocol. |
| `vodEgressBytes` | Recordings played back or downloaded, and recordings written to your own bucket. |
| `vodRecordingBytes` | Recordings written to managed storage. |
| `storedGbSeconds` | Managed storage held over time, in GB·second. |
| `transcode480Seconds`, `transcode720Seconds`, `transcode1080Seconds` | Transcoded renditions, while someone watches them. |
| `agentSeconds` | Time a voice agent is live. |

Each meter's price is on the [pricing page](https://moq.pro/#pricing) and the project's **Cost** page.

## Free allowance

Each account gets a monthly delivery allowance, shared by live and recording delivery, and an archive allowance for recording and storage. The projects an account owns share them, oldest project first. Transcoding and voice have no allowance.

Without a payment method, a project that uses far past its allowance stops accepting connections until a card is added. To add a card, open the project's **Billing** page. The owner can also create a card-entry link for whoever holds the card:

```sh
curl --fail-with-body --silent --show-error -X POST "$API/projects/$PID/payment/setup-link" \
  -H "Authorization: Bearer $MOQ_API_TOKEN" | jq -er '.url'
```

## Read usage

This month so far, with the share of the allowance this project has drawn:

```sh
curl --fail-with-body --silent --show-error "$API/projects/$PID/usage/current" \
  -H "Authorization: Bearer $MOQ_API_TOKEN"
```

History, one row per day for the last 30 days:

```sh
curl --fail-with-body --silent --show-error "$API/projects/$PID/usage?period=day" \
  -H "Authorization: Bearer $MOQ_API_TOKEN"
```

`period` is `minute`, `hour`, `day`, `month`, `year`, or `forever`, and `from` and `to` pick the window. Each row's `costMicros` is its charge before the allowance, in micro-USD (1,000,000 is USD 1). The other fields split usage by protocol and count sessions for display; they are never billed again. `GET /v1/account/usage` shows how your owned projects share the allowance. The account token needs `usage:read`.

## Cap spend

A spend cap pauses the project once the month's bill reaches it: live connections and recording playback stop until you raise or remove the cap, or the month ends. The owner gets an email at 80%. This caps the month at USD 100:

```sh
curl --fail-with-body --silent --show-error -X PATCH "$API/projects/$PID/spend-cap" \
  -H "Authorization: Bearer $MOQ_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"spendCapMicros":100000000}'
```

Send `null` to remove it. The account token needs `billing:write`.

## Limit sessions

Session limits bound how many live sessions one token, or one address, may hold on each relay, so a leaked token cannot fan out. This allows 5 per token and 20 per address:

```sh
curl --fail-with-body --silent --show-error -X PATCH "$API/projects/$PID/limits" \
  -H "Authorization: Bearer $MOQ_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"token":5,"remote":20}'
```

An IPv6 address counts by its /64. Send `null` for no limit. The account token needs `settings:write`.

## Invoices

Each project is invoiced monthly in USD through Stripe. List past invoices with `GET /v1/projects/{pid}/invoices`, or open the Stripe portal from the project's **Billing** page to download them and change the card.