---
title: "Read a user's usage this billing cycle"
method: GET
path: "/v1/admin/users/{user_id}/usage"
tags: ["Admin"]
---

# Read a user's usage this billing cycle

`GET /v1/admin/users/{user_id}/usage`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/admin/users/{user_id}/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`)

The same answer `GET /v1/users/me/usage` gives the account itself: runs, indexed storage and the plan-capped counts, per project and against the rung. Needs the `admin` role.

## Path parameters

- `user_id` string, required

## 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.
- `403`: The caller does not hold the `admin` role.
- `404`: No such user.

---

[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)