GET /v1/account/credits/ledger

Account credit ledger

Access

Authenticated (self)

Cost

Free

Rate limit

60 / minute per account

Quota

None

The account credit usage history: the append-only ledger of grants, top-ups, debits, and adjustments, newest first with opaque cursor pagination. Free on every plan.

Query parameters

limit integer default: 50

min 1, max 100
cursor string

max 256 chars

Responses

200 A page of ledger entries and the next-page cursor
- entries array of CreditLedgerEntry required
  
  A page of ledger movements, newest first.
  - id string required
    
    Identifier of this ledger entry.
  - kind string required
    
    The movement: `grant` (the plan allotment for a period), `topup` (credits purchased), `debit` (credits spent on a call), or `adjustment` (a manual correction).
  - amount integer required
    
    Credits moved, SIGNED: positive on `grant` and `topup`, negative on `debit`, either sign on `adjustment`. Sum the column to reconcile; do not take absolute values.
  - actorKind string required
    
    Who caused the movement: `member`, `key`, or `system` (grants, purchase webhooks, and admin adjustments).
  - actorId string | null required
    
    The member or key that caused it. Null on a `system` movement.
  - operation string | null required
    
    The API operation that was charged, on a `debit`. Null on grants, top-ups, and adjustments.
  - ref string | null required
    
    The idempotency reference behind this entry, so a redelivered webhook or a retried grant converges on one row instead of double-crediting.
  - createdAt string required
    
    When the movement was recorded, as an ISO 8601 instant.
- nextCursor string | null required
  
  Opaque token for the next page: pass it back as `cursor`. Null on the last page. Do not parse or construct it.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.