---
title: "List credit ledger"
method: GET
path: "/payment/v1/credits/ledger"
tags: ["Billing"]
---

# List credit ledger

`GET /payment/v1/credits/ledger`

Paginated credit-ledger transaction history. Ledger reads are served
from ClickHouse; a rare storage-tier outage returns an empty
`transactions` array rather than a 5xx.

**Window rules**

- `from` defaults to `to - 7 days`, `to` defaults to now.
- The span between `from` and `to` cannot exceed **90 days**. A wider
  span returns 400. Page through longer periods by making multiple
  calls with shifted `from`/`to`.
- `from` cannot be earlier than **2026-03-02T00:00:00Z**. Older
  historical data is not available via API; contact support for bulk
  exports.
- `from > to` returns 400.

**Filters**

- `type` filters to a single transaction type. `PAYMENTS` is a
  virtual filter that returns both `CREDIT_PURCHASE` and
  `AUTO_RELOAD` rows.
- `scope` filters `USAGE_DEDUCTION` rows by product category.

## Query parameters

- `limit` integer
- `offset` integer
- `from` string, date-time
- `to` string, date-time
- `type` 'SIGNUP_BONUS' | 'CREDIT_PURCHASE' | 'AUTO_RELOAD' | 'USAGE_DEDUCTION' | 'ADMIN_ADJUSTMENT' | 'COUPON_CREDIT' | 'MIGRATION' | 'PAYMENTS'
- `scope` 'platform' | 'voice_ai' | 'voice_models'

## Response `200`

Paginated ledger with summary + query window echo.

- BillingLedgerResponse
  - `success` boolean, required
  - `data` object, required
    - `transactions` BillingLedgerEntry[], required
      - `id` string, required — Ledger row identifier.
      - `transactionType` 'SIGNUP_BONUS' | 'CREDIT_PURCHASE' | 'AUTO_RELOAD' | 'USAGE_DEDUCTION' | 'ADMIN_ADJUSTMENT' | 'COUPON_CREDIT' | 'MIGRATION', required
      - `amount` number, required — Signed credit delta in USD. Positive for additions (`CREDIT_PURCHASE`, `AUTO_RELOAD`, `COUPON_CREDIT`, `SIGNUP_BONUS`), negative for spend (`USAGE_DEDUCTION`).
      - `balanceAfter` number, required — Balance after this row was applied.
      - `featureId` string, nullable — Product feature that triggered the row (e.g. `tts.generate`, `waves.stt`). Only set on `USAGE_DEDUCTION`.
      - `referenceId` string, nullable — External reference tying this row to a purchase, coupon, or admin action.
      - `description` string, nullable
      - `createdAt` string, date-time, required
      - `callId` string, nullable — Associated call ID, when the row was produced by a call.
      - `agentId` string, nullable
      - `requestId` string, nullable
    - `total` integer, required — Total row count matching the filters (across all pages).
    - `hasMore` boolean, required — True when more rows exist beyond `offset + limit`.
    - `summary` object, required
      - `totalCreditsConsumed` number, required — Sum of `USAGE_DEDUCTION` magnitudes across the window.
      - `totalCreditsAdded` number, required — Sum of positive rows (purchases, auto-reloads, coupon credits, signup bonuses) across the window.
    - `period` object, required
      - `from` string, date-time, required — Echo of the effective lower bound (defaults to seven days before `to` when not supplied).
      - `to` string, date-time, required — Echo of the effective upper bound (defaults to server-now when not supplied).

## Other responses

- `400` — Query-window validation failed. Common cases: - `from` earlier than `2026-03-02T00:00:00Z`. - Span between `from` and `to` exceeds 90 days. - `from > to`. - Malformed date string in `from` or `to`.
- `401` — Unauthorized access

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/c2d0eb64b01a/schema)