---
title: "List the current account's credit ledger"
method: GET
path: "/v1/users/me/credits"
tags: ["Users"]
---

# List the current account's credit ledger

`GET /v1/users/me/credits`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/users/me/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 model-credit ledger, newest first, with the balance the whole ledger sums to. The ledger is append-only: a correction is a new line, never an edit.

A `usage` line is managed model spend, written as the meter is reconciled every 15 minutes per project, so the ledger grows by a line per project per window that spent anything. Filter with `kind`.

The other side of a marketplace line is another account's project, so a `fee` or `earned` line names the cycle it settles, not that project.

## Query parameters

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

## Response `200`

A page of the ledger.

- AccountCreditEntryPage
  - `data` AccountCreditEntry[], required
    - `id` string, required: Public ledger-line ID (cre_ prefix).
    - `kind` 'included' | 'purchased' | 'granted' | 'usage' | 'earned' | 'fee', required: Where the credit came from. `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. `usage` is managed model spend, debited from the meter. `fee` is what this account paid marketplace publishers; `earned` is its share of the fees its own listings were paid.
    - `amount_usd` number, required: US dollars, signed. Negative lines are spend or corrections.
    - `reason` string, nullable, required: What the line is for.
    - `project_id` string, nullable, required: This account's project the line belongs to: the one whose meter produced a `usage` line, that paid a `fee` or earned an `earned`. Null for a line to the account itself.
    - `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 its projects. Null when at least one project has never been reconciled.
  - `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.

---

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