---
title: "Paginate the credits ledger"
method: GET
path: "/api/v1/credits/ledger"
tags: ["Governance"]
---

# Paginate the credits ledger

`GET /api/v1/credits/ledger`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/credits/ledger`
- Auth: HTTP bearer

Cursor-paginated view over `credits_ledger`. Keyset pagination by `(created_at, id)` descending, Stripe-style `{ data, has_more, next_cursor }`.

Ownership (a child key is always pinned to its own `api_key_id`):
- **child** → its own `api_key_id`; passing `?api_key_id=` for a foreign key returns **403**.
- **master** → the whole organization (sub-keys share the master's `user_id`); `?api_key_id=` is validated for membership (404 anti-enumeration otherwise).
- **solo/legacy** → the caller's `user_id`.

The row subset is Zero-Retention-safe: `meta` (which may carry a filename) is never returned in the clear.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `kind` 'purchase' | 'consumption' | 'admin_gift' | 'refund'
- `api_key_id` string, uuid
- `cursor` string
- `limit` integer

## Response `200`

A page of ledger entries.

- LedgerResponse
  - `data` LedgerEntry[], required
    - `id` string, uuid, required
    - `created_at` string, date-time, required
    - `amount` number, required: Signed credit delta: positive on purchase/refund/gift, negative on consumption.
    - `kind` 'purchase' | 'consumption' | 'admin_gift' | 'refund', required
    - `reference_type` string, nullable
    - `reference_id` string, nullable
    - `job_id` string, uuid, nullable
    - `api_key_id` string, uuid, nullable: Sub-key charged; null for dashboard-level consumption.
    - `key_prefix` string, nullable
    - `description` string, nullable
    - `operation_type` string, nullable
    - `quantity` number, nullable
    - `unit_cost` number, nullable
  - `has_more` boolean, required
  - `next_cursor` string, nullable: Opaque keyset cursor for the next page; null on the last page.

## Other responses

- `401`: INVALID_API_KEY.
- `403`: FORBIDDEN — a child key requested a foreign `api_key_id`.
- `429`: RATE_LIMITED — RPM exceeded.

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)