Users

List the current account's credit ledger

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.

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)

Query parameters

kind'included' | 'purchased' | 'granted' | 'usage' | 'earned' | 'fee'

Only lines of this kind.

limitinteger

Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an integer it is 400.

cursorstring

The next_cursor of the previous page.

Response

A page of the ledger.

credit_balance_usdnumber 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_atstring 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_cursorstring nullable required

Pass as cursor for the next page; null on the last one.

Example response

{
  "data": [
    {
      "id": "cre_V1StGXR8Z5jdHi6B",
      "kind": "usage",
      "amount_usd": -0.42,
      "reason": "Model usage, 2026-07.",
      "project_id": "proj_V1StGXR8Z5jdHi6B",
      "created_at": "2026-07-14T12:15:00.000Z"
    }
  ],
  "credit_balance_usd": 8.98,
  "spend_reconciled_at": "2026-07-14T12:15:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.