---
title: "Usage Ledger"
method: GET
path: "/api/usage/ledger"
tags: ["Usage"]
---

# Usage Ledger

`GET /api/usage/ledger`

## Request

- Base URL: `https://api.kolens.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kolens.ai/api/usage/ledger`
- Auth: HTTP bearer

Unified credit history — debits (scrapes) AND credits (top-ups).

This is the feed the credits page renders. Before this endpoint the
page only ever showed debits, so a user could watch their balance go
down but never saw the matching ``+N credits`` when they bought a
pack. We merge:

  1. Debits — completed jobs that actually charged credits
     (``credits_charged`` > 0) from our Postgres ``search_jobs``.
  2. Credits — personal top-ups from the Supabase ``credit_purchases``
     table (via ``CreditsService.list_purchases``), the same rows the
     Orders page shows.

Both are sorted newest-first and capped at ``limit``. If Supabase is
unreachable / unconfigured (local dev, CI) the credit side is simply
empty and the feed degrades to debits-only — never an error.

## Query parameters

- `limit` integer

## Headers

- `x-kolens-user-id` string, nullable

## Response `200`

Successful Response

- LedgerOut
  - `user_id` string, required
  - `limit` integer, required
  - `entries` LedgerEntry[]
    - `id` string, required
    - `kind` 'debit' | 'credit', required
    - `delta` number, required
    - `created_at` string, nullable
    - `label` string
    - `job_id` string, nullable
    - `status` string, nullable
    - `data_source` string, nullable
    - `source` object, nullable
    - `amount_cents` integer, nullable
    - `stripe_session_id` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)