> ## Documentation Index
> Fetch the complete documentation index at: https://developers.supapost.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Ledger Entries

> Paginated credit-ledger history for the active team.

Returns the team's credit transactions in reverse-chronological order. Every debit (image/video generation, render) and credit (monthly reset, refund, coupon claim, top-up) is a row. Useful for building a usage dashboard, reconciling end-of-month spend, or surfacing "why did my balance drop?" to the user.

Scoped to the team selected by the caller's session / API key. RLS already enforces team membership.

## Query Parameters

<ParamField query="before" type="string (ISO-8601)">
  Return rows strictly older than this timestamp. Use the `created_at`
  of the last row on the previous page as the cursor.
</ParamField>

## Response

```json 200 theme={null}
{
  "entries": [
    {
      "id": 12345,
      "delta": -8,
      "reason": "image_gen",
      "model_id": "fal:nano-banana-pro",
      "user_id": "user-uuid",
      "route": "/generate/image",
      "balance_after": 342,
      "metadata": { "job_id": "job-uuid" },
      "created_at": "2026-04-21T10:15:00Z",
      "auth_mode": "jwt",
      "api_key_id": null
    }
  ],
  "has_more": true
}
```

### Fields

<ResponseField name="entries[].delta" type="integer">
  Signed credit change. Negative for spends, positive for grants /
  refunds / top-ups.
</ResponseField>

<ResponseField name="entries[].reason" type="string">
  One of `image_gen`, `video_gen`, `render`, `monthly_reset`,
  `initial_grant`, `plan_change_topup`, `refund`, `admin_grant`,
  `coupon_claim`.
</ResponseField>

<ResponseField name="entries[].model_id" type="string | null">
  Model that incurred the debit, for generation rows. `null` for
  non-generation reasons.
</ResponseField>

<ResponseField name="entries[].balance_after" type="integer | null">
  Monthly-plan balance immediately after this row was written.
</ResponseField>

<ResponseField name="entries[].auth_mode" type="string | null">
  `api_key` (agent / server-to-server), `jwt` (dashboard session), or
  `null` (system-issued row like `monthly_reset`).
</ResponseField>

<ResponseField name="has_more" type="boolean">
  `true` when more rows exist older than the last returned row. Page
  again with `?before=<last_created_at>`.
</ResponseField>

## Example

```bash cURL theme={null}
# First page
curl https://api.supapost.so/billing/ledger \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl "https://api.supapost.so/billing/ledger?before=2026-04-21T10:15:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```