> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://onepin.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://onepin.ai/docs/_mcp/server.

# Check usage

Report your workspace's usage over a rolling window (`30d`, `60d`, or `90d`). Needs the `workspace:read` scope.

#### Python

```python
from onepin import OnepinClient

client = OnepinClient()

summary = client.usage.usage_summary(range="30d").data
by_language = client.usage.usage_by_language(range="30d").data
activity = client.usage.usage_activity(range="30d").data
```

#### CLI

```bash
onepin usage summary --range 30d
onepin usage by-language --range 30d
onepin usage activity --range 30d
```

## What the summary counts

The summary reports several different populations, and they are deliberately not addable to each other:

| Field             | Counts                                                                                       | Unit         |
| ----------------- | -------------------------------------------------------------------------------------------- | ------------ |
| `characters`      | Characters processed across the workspace                                                    | characters   |
| `audio.total_ms`  | **Delivered** audio length — the delivered take per generator on each line, retries excluded | milliseconds |
| `corrected.total` | Words respliced by the [Pronunciation Corrector](/docs/workflow/pronunciation-corrector)     | **words**    |
| `lines`           | Script lines generated                                                                       | lines        |
| `runs`            | Run counts by status                                                                         | runs         |
| `credits`         | Credit consumption and quota for your billing period                                         | credits      |

Volume synthesized through a [connected provider key](/docs/guides/bring-your-own-key) is counted here like any other — `characters` and `audio.total_ms` include it — while it charges `0` credits. Usage and credits are two different questions, and BYOK is where they diverge most visibly.

> **Warning**
>
> `corrected.total` is in **words**, not characters — never add it to `characters`. And `audio.total_ms` is a narrower population than the per-workflow `runs summary`'s `delivered_audio_ms`, which counts completed runs only. The two are not expected to reconcile.

## Estimate a run before you start it

```bash
onepin workflows preview-run <WORKFLOW_ID>
```

```python
est = client.workflows.preview_run(workflow_id).data
```

Alongside `min_credits` / `expected_credits` / `max_credits` and `can_run`, the estimate now tells you whether the run will spill past your allowance:

| Field                           | Meaning                                                           |
| ------------------------------- | ----------------------------------------------------------------- |
| `will_incur_overage`            | The run is expected to go past your included credits              |
| `estimated_overage_cents`       | What that spill is expected to cost, in cents                     |
| `overage_rate_cents_per_credit` | The rate it's charged at; null when your plan has no overage rate |

## Credits, buckets, and overage

Credits come out of two buckets, and the distinction matters when you're reading a balance from `GET /api/v1/users/me/credits`:

* **`monthly_balance`** — the current paid cycle's allowance. Replaced at each renewal, and `0` on Free.
* **`free_balance`** — a one-time lifetime grant. Never expires, and spent **last**, after the monthly bucket.

`balance` is the sum of the two and is what gating decisions use (`remaining` is a display alias of it). `overage_cents` is what you've been billed past your allowance so far this cycle. `credits_absorbed` is the sub-credit remainder discounted by floor-rounding — Onepin's rounding in your favour, not a charge.

Your plan's own limits — including `overage_rate_cents_per_credit`, whether credits renew `monthly` or are `one_time`, and whether downloads are enabled — come from `GET /api/v1/users/me/limits`, or `GET /api/v1/workspaces/{workspace_id}/plan` for the workspace-scoped view (which resolves to the organization's plan on an org workspace).

> **Note**
>
> The overage, audio, and corrected-word fields are new. They are live on the API today; the Python SDK's typed models pick them up in its next release, so read them off the response payload until then.

## Related

* [Run a workflow](/docs/guides/run-a-workflow) — start, watch, download
* [Workflow](/docs/workflow/overview) — estimating cost per node
* [Pronunciation Corrector](/docs/workflow/pronunciation-corrector) — what `corrected` counts
* [Bring your own key](/docs/guides/bring-your-own-key) — volume that counts but doesn't charge