---
title: "Get the current account's usage this billing cycle"
method: GET
path: "/v1/users/me/usage"
tags: ["Users"]
---

# Get the current account's usage this billing cycle

`GET /v1/users/me/usage`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/users/me/usage`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

What the account uses this billing cycle, per project and against its plan: runs, indexed storage, and the counts the plan caps — projects, active channels and triggers.

How many runs the account has made this billing cycle, and how many its plan includes. A **run is one agent generation or one tool call** — the unit every rung is priced in. Every tool call counts, including those an agent makes inside a generation; a `client` tool counts nothing.

Counted across the projects this account is the billing owner of, over the current UTC calendar month, from the meter itself. Archived projects are included: the runs they already made were made.

**On the `free` plan the allowance is enforced.** An account that has used it is refused `403 plan_limit_reached` with `resource: "runs"` on everything that starts a generation and on a direct tool call — on its own provider credential as much as on a managed model, because a run is a run — until the billing month turns or it upgrades. On `pro` and `business` nothing is refused: runs past the allowance are billed at the overage rate those plans are sold with. A contract plan is not counted.

The other thing that stops a managed-model generation is a negative credit balance, which is `GET /v1/users/me/billing`, and it never applies to your own credential.

**This route counts live; the refusal reads a figure counted every few minutes.** So the two can differ by a burst: this is the more current number, and a refusal quotes the one it actually enforced.

It is also more expensive than the balance read: it reads the runtime several times per project. Poll it on the order of minutes, not seconds. A figure that could not be read is `null` rather than failing the request.

## Response `200`

The account's usage for the cycle.

- UserUsage
  - `cycle_from` string, date-time, required: Start of the billing cycle the runs were counted over — the first instant of the current UTC calendar month.
  - `pending_spend_usd` number, nullable, required: Model and embedding spend metered since the balance was last reconciled, across every project the account pays for. `null` when at least one project's meter could not be read.
  - `spendable_balance_usd` number, nullable, required: The credit balance less `pending_spend_usd`. A managed generation can be refused with `402 insufficient_credit` while the credit balance still reads positive; while this is zero or above, none is. Check it before starting work that runs several generations. `null` when `pending_spend_usd` is.
  - `projects` AccountProjectUsage[], required: Every project the account pays for, oldest first, archived ones included. Empty for an account with no projects.
    - `project_id` string, required
    - `name` string, nullable, required: The project's name; `null` when it could not be read.
    - `status` 'active' | 'archived', required
    - `runs` integer, nullable, required: Runs this cycle; `null` when this project's meter could not be read.
    - `triggers` integer, nullable, required: Triggers the project holds; `null` when they could not be counted.
    - `channels` integer, required: Channels in the `active` state, the ones the `channels` limit counts. A `disabled` one does not count.
    - `storage` object, required
      - `used` number, nullable, required: GB of indexed storage as of the last sample; `null` when the project has never been sampled.
      - `sampled_at` string, date-time, nullable, required: When `used` was sampled.
    - `pending_spend_usd` number, nullable, required: This project's spend metered since the balance was last reconciled; `null` when its meter could not be read.
  - `limits` UsageLimits, required: Each plan-limited resource, counted across every project the account pays for, beside the rung's ceiling — keyed by the `resource` a `403 plan_limit_reached` names, whose `details` carry the same `used` and `limit`.
    - `projects` UsageLimit, required
      - `used` number, nullable, required: How much is held; `null` when a project's part of it could not be read.
      - `limit` number, nullable, required: The rung's ceiling; `null` when it sets none.
    - `channels` UsageLimit, required
      - `used` number, nullable, required: How much is held; `null` when a project's part of it could not be read.
      - `limit` number, nullable, required: The rung's ceiling; `null` when it sets none.
    - `triggers` UsageLimit, required
      - `used` number, nullable, required: How much is held; `null` when a project's part of it could not be read.
      - `limit` number, nullable, required: The rung's ceiling; `null` when it sets none.
    - `storage` UsageLimit, required
      - `used` number, nullable, required: How much is held; `null` when a project's part of it could not be read.
      - `limit` number, nullable, required: The rung's ceiling; `null` when it sets none.
    - `runs` UsageLimit, required
      - `used` number, nullable, required: How much is held; `null` when a project's part of it could not be read.
      - `limit` number, nullable, required: The rung's ceiling; `null` when it sets none.

## Other responses

- `401`: Missing or invalid credentials.

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)