---
title: "Read a user's credit ledger"
method: GET
path: "/v1/admin/users/{user_id}/credits"
tags: ["Admin"]
---

# Read a user's credit ledger

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

## Request

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

A cursor page of the account's credit lines, newest first, with the balance they sum to. Needs the `admin` role — including for the account's own owner, who reads their own balance at `GET /v1/users/me/billing` rather than here. That answers what is left; this is the line-by-line record behind it.
What an operator reads it for is writing a correction: the line that was wrong stays on the record, so it has to be legible before it can be compensated for.

## Path parameters

- `user_id` string, required

## Query parameters

- `kind` 'included' | 'purchased' | 'granted' | 'usage' | 'earned' | 'fee'
- `limit` integer
- `cursor` string

## Response `200`

A page of the ledger.

- CreditEntryPage
  - `data` CreditEntry[], required
    - `id` string, required: Public ledger-line ID (cre_ prefix).
    - `kind` 'included' | 'purchased' | 'granted' | 'usage' | 'earned' | 'fee', required: Where the credit came from, which is also its accounting line. `included` is a plan's monthly allowance and does not carry past the cycle; `purchased` is a top-up and never expires; `granted` is credit naturali gave away. `usage` is managed model spend, debited from the meter — always negative. `fee` is what a consumer paid a marketplace publisher (negative); `earned` is the publisher's share of funded fees, and the only withdrawable kind.
    - `amount_usd` number, required: US dollars, signed: positive added credit, negative corrected an earlier line.
    - `reason` string, nullable, required: Why it was granted, as the operator wrote it.
    - `project_id` string, nullable, required: The project whose metered usage produced this line, for a `usage` debit. Null for every other kind: a grant, a top-up and an allowance are to the account rather than to one of its projects.
    - `counterparty_project_id` string, nullable, required: The other side of a marketplace line: the publisher project on a `fee`, the consumer project on an `earned`. Null for every other line.
    - `granted_by_user_id` string, nullable, required: The operator who authorized it. Null for credit no person granted — a plan's included allowance, or a payer's own top-up.
    - `created_at` string, date-time, required
  - `credit_balance_usd` number, required: The sum of the whole ledger, not only of this page. Spend is included as it is reconciled, so read it with `spend_reconciled_at`.
  - `spend_reconciled_at` string, date-time, nullable, required: When this account's managed spend was last compared against the meter — the oldest such moment across the projects it pays for, so it describes the whole balance. Null when at least one project has never been reconciled, which is also true of an account with none.
  - `next_cursor` string, nullable, required: Pass as `cursor` for the next page; null on the last one.

## Other responses

- `400`: The request was malformed or failed validation.
- `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)