# Usage

> The API operations about usage, each with its input, its output and an example.

The operations about usage. Each one is a `POST` with a JSON object as its body: [Making a request](/docs/api#start) has the rules they share.

## Usage this month

`POST /api/v1/usage.get` · Read

How many events the workspace recorded in one UTC month, per site and in total, next to the plan's monthly allowance (quota). An event is a page view or a custom event. Leave month out for the current month. locked says whether the dashboards are locked because the allowance was reached; while they are, report operations answer 402 workspace_locked but this one keeps working, so a program can learn why. Visits are still counted under that lock, up to the safety ceiling in breakerEvents. Nothing here is a price.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | optional | The UTC month to report, YYYY-MM. Left out, the current month. |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `period` | string | always | The UTC month the numbers are for, YYYY-MM. |
| `quota` | number | always | The plan's monthly event allowance, for all sites of the workspace together. |
| `sites` | array of object | always | Events recorded per site in the month, most first. Every site is listed, also with zero. A site deleted during the month keeps its row, because its events still count. |
| `total` | number | always | Events recorded in the month across all sites. Compare it with quota. |
| `locked` | boolean | always | True when the dashboards are locked for the rest of the month because the allowance was reached. Visits are still being counted. |
| `lockedUntil` | number \| null | always | When that lock lifts by itself (the first of next month, UTC) in milliseconds since 1970 UTC. Null when not locked. |
| `warnAtPct` | number | always | The share of the allowance, in percent, at which the workspace owner is warned by email. |
| `breakerEvents` | number | always | The safety ceiling: the number of events in a month at which collection pauses until the next month or a larger plan. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/usage.get \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**CLI**

```bash
clearsaga usage get --input '{}'
```

**MCP**

```text
Tool: usage_get
Arguments: {}
```

Run `clearsaga help usage get` for one flag per field.