Admin

Read a user's credit ledger

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.

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)

Path parameters

user_idstring required

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

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

Example response

{
  "data": [
    {
      "id": "cre_V1StGXR8Z5jdHi6B",
      "kind": "granted",
      "amount_usd": 25,
      "reason": "design partner",
      "project_id": "proj_V1StGXR8Z5jdHi6B",
      "granted_by_user_id": "user_V1StGXR8Z5jdHi6B",
      "created_at": "2026-09-02T00:00:00.000Z"
    }
  ],
  "credit_balance_usd": 30,
  "spend_reconciled_at": "2026-09-04T14:45:00.000Z"
}

Changes

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