Skip to main content
GET
/
billing
/
ledger
List Ledger Entries
curl --request GET \
  --url https://api.example.com/billing/ledger
{
  "entries[].delta": 123,
  "entries[].reason": "<string>",
  "entries[].model_id": {},
  "entries[].balance_after": {},
  "entries[].auth_mode": {},
  "has_more": true
}
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

​
before
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.

​
Response

200
{
  "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

​
entries[].delta
integer
Signed credit change. Negative for spends, positive for grants / refunds / top-ups.
​
entries[].reason
string
One of image_gen, video_gen, render, monthly_reset, initial_grant, plan_change_topup, refund, admin_grant, coupon_claim.
​
entries[].model_id
string | null
Model that incurred the debit, for generation rows. null for non-generation reasons.
​
entries[].balance_after
integer | null
Monthly-plan balance immediately after this row was written.
​
entries[].auth_mode
string | null
api_key (agent / server-to-server), jwt (dashboard session), or null (system-issued row like monthly_reset).
​
has_more
boolean
true when more rows exist older than the last returned row. Page again with ?before=<last_created_at>.

​
Example

cURL
# 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"