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

# Usage and budgets

> Read your monthly usage per meter, day, and project, set a budget that caps overage for each meter, and get notified at 50, 80, and 100 percent.

Squasher counts your usage every day. The usage report shows each meter for one month. A budget
caps the overage of one meter. Usage notifications tell owners and billing admins when usage
reaches a threshold.

## Read your usage

The usage report covers one calendar month (UTC). For each meter it shows:

* the amount used this month, the included amount, and the overage
* the estimated overage charge (your invoice is the record)
* the budget and its state
* a daily series
* the share of each project

Telemetry is measured in GB (1,000,000,000 bytes) of uncompressed data as Squasher receives it. It
covers errors, logs, traces, metrics, web vitals, and AI observations. The report gives the exact
bytes and the month total in whole GB.

Two numbers are counted but never billed: **error events** and **AI observations** (model calls
that your app reports). The report shows them per day and per project.

A meter that is counted but not billed yet shows `billing_status: "not_billed"` and a charge of 0.

In the dashboard, open **Organization > Usage and billing** and select **Usage**. Choose a month at
the top. The page shows the estimated bill, one card per meter with its daily usage and projects,
the usage statistics, the budgets, and the last twelve months. A meter that is counted but not
billed yet shows **Counted, not billed**.

## Budgets

A budget is the most overage that one meter can add to your bill in a month. Paid plans get a
default budget for every meter: $50 on Pro, $150 on Team, and \$500 on Scale. You can change the
amount and the mode of each meter.

| Mode | At 100% of the budget |
| - | - |
| `alert` | Squasher notifies you. Overage continues. |
| `stop` | Squasher refuses new usage of the meter until the month ends or you raise the budget. |

Some meters allow only one mode:

* **Monitor checks** and **phone alerts** (SMS and voice) allow only `alert`. Monitoring and paging
  never stop.
* **AI credits** allow only `stop`. At the budget, automatic AI work and new chat pause.

When you raise a budget that has stopped a meter, Squasher accepts new usage again within about a
minute.

The Free plan has no budgets. It stops at its included amounts. To continue, upgrade the plan.

Only owners and billing admins can change budgets. Every member can read them. To change a
budget in the dashboard, go to **Usage and billing > Usage > Budgets**, change the amount or the
mode, and select **Save budgets**.

## Usage notifications

Squasher notifies owners and billing admins when a meter reaches:

* 50%, 80%, and 100% of the included amount
* 50%, 80%, and 100% of the budget

Each notification goes to the [notification inbox](https://docs.squasher.ai/features/alerts.md#read-your-notification-inbox)
and by email. Each threshold notifies once per meter and month. To stop these notifications, turn
off the **Usage** category in your notification preferences.

While a meter is counted but not billed yet, Squasher sends its included-amount notifications and,
for a `stop` budget, its budget notifications. An `alert` budget on such a meter sends nothing,
because nothing is charged.

## Refused requests

When a meter stops, Squasher refuses new data with HTTP `402` and these headers:

| `x-squasher-limit` | Why |
| - | - |
| `free_monthly_telemetry` | The Free plan used its included telemetry. |
| `budget_telemetry` | Telemetry reached a `stop` budget. |
| `free_monthly_replays` | The Free plan used its included replays. |
| `budget_replays` | A new replay session reached a `stop` budget. |

Every refusal also sends `x-should-retry: false`, so SDKs do not retry the request. OTLP over gRPC
returns `RESOURCE_EXHAUSTED`. A replay session that started before the stop keeps its segments.

## API

```bash theme={null}
# Usage of October 2026
curl -H "Authorization: Bearer $SQUASHER_API_KEY" \
  "https://api.squasher.ai/v1/organizations/$ORGANIZATION_ID/usage?period=2026-10"

# Budgets
curl -H "Authorization: Bearer $SQUASHER_API_KEY" \
  "https://api.squasher.ai/v1/organizations/$ORGANIZATION_ID/budgets"
```

To change budgets, send `PUT /v1/organizations/{organization_id}/budgets` from a signed-in session.
An API key can read usage and budgets but cannot change them. See the
[Organizations API](https://docs.squasher.ai/api-reference/organizations.md).

## CLI

```bash theme={null}
squasher usage                     # this month
squasher usage --month 2026-09     # another month
squasher budgets list
squasher budgets set logs --amount-usd 100 --mode stop
squasher budgets set replays --default
```

`--default` restores the plan default amount and mode. Add `--json` for machine-readable output.

## MCP

Hosted MCP exposes `organizations.getUsage`, `organizations.listBudgets`, and
`organizations.updateBudgets`. Search for "usage" or "budget" to find them. A change needs a
signed-in owner or billing admin.

Related: [Plans and limits](https://docs.squasher.ai/features/plans-and-billing.md).


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