---
title: "List the workspace credit ledger"
method: GET
path: "/credits/transactions"
tags: ["Credits"]
---

# List the workspace credit ledger

`GET /credits/transactions`

## Request

- Base URL: `https://inkseal.net/api/v1`
- URL: `https://inkseal.net/api/v1/credits/transactions`
- Auth: HTTP bearer

The workspace's credit ledger, newest first: what was bought, what was spent, and what came back.

Each row carries a signed `amount` (negative spends, positive adds), the `balanceAfter` that resulted, and a stable `reason` code to branch on. `type` alone is too coarse to act on, because a `refund` is either a failed send returning its credit or a purchase being reversed; the `reason` code separates them.

Rows are redacted before they leave the process. There is no ledger row id, no user id, and no Stripe identifier: a purchase is described by its reason and its amount, and the payment behind it stays in the dashboard with the human who made it. `reference` is populated only when the reference is a public identifier, which today means envelopes and nothing else.

Ordering breaks ties on the underlying row id as well as the timestamp, so two entries written in the same transaction cannot swap places between two pages of the same walk.

## Query parameters

- `page` integer
- `limit` integer

## Response `200`

A page of ledger entries, newest first.

- object
  - `data` CreditTransaction[], required
    - `type` 'purchase' | 'usage' | 'refund' | 'adjustment', required: The coarse category. Branch on `reason` instead: a `refund` is either a failed send returning its credit or a purchase being reversed.
    - `amount` integer, required: Signed. Negative spends credits, positive adds them.
    - `balanceAfter` integer, required: The workspace balance immediately after this entry was applied.
    - `reason` 'credit_purchase' | 'credit_purchase_usdc' | 'purchase_refunded' | 'envelope_sent' | 'envelope_send_refunded' | 'signer_reassigned' | 'manual_adjustment' | 'unclassified', required: A stable code naming what happened, safe to branch on without reading the description. `credit_purchase` is a card purchase; `credit_purchase_usdc` is a pack an agent bought itself over x402, which is not refundable. `signer_reassigned` is the one signer credit charged when the sender's own signer part is reassigned to someone else after the send. `unclassified` covers any entry written by a source this vocabulary does not yet name.
    - `description` string, nullable, required: Free text recorded with the entry, when there is any.
    - `reference` object, nullable, required: The resource the entry refers to, present only when that reference is a public identifier. Purchases reference an internal payment row and so answer null here.
      - `type` 'envelope', required
      - `id` string, required: The envelope's public identifier.
    - `createdAt` string, date-time, required
  - `pagination` Pagination, required: Where the returned page sits in the full result set.
    - `page` integer, required: The 1-based page returned.
    - `limit` integer, required: Items per page, as requested.
    - `total` integer, required: Total items matching the query.
    - `totalPages` integer, required: `ceil(total / limit)`.

## Other responses

- `400`: The request is malformed or the resource is in the wrong state for a synchronous check. Codes: `validation_error`, `invalid_body`, `invalid_parameter`, `invalid_idempotency_key`, `invalid_event_id`, `invalid_file`, `invalid_url`, `invalid_status`, `key_mismatch`, `no_signers`, `not_completed`, `envelope_exists`, `document_not_ready`, `upload_failed`.
- `401`: The credential is missing, malformed, unknown, expired, revoked, or past its rotation grace window. Code: `unauthorized`. Every authentication failure is deliberately indistinguishable.
- `403`: The credential is valid but may not do this. Codes: `insufficient_scope` (the route's scopes are not all held; `details` names `requiredScopes` and `missingScopes`), `forbidden` (the capability check on the resolved resource failed), `scope_escalation` (a grant wider than the caller's own was requested).
- `429`: A limit was reached. Codes: `rate_limited` (the credential's per-bucket HTTP limit, or the per-workspace detection throttle), `workspace_limit_exceeded` (a workspace content or send limit; `details.limit` names it), `daily_budget_exceeded` (the workspace's daily detection budget). The four rate-limit headers are sent on this response and on no successful one, so a client cannot read its remaining budget without being refused. Retrying after `Retry-After` is always safe: a rate-limit refusal happens before the handler runs.
- `503`: A dependency the request needs is unreachable and nothing was changed. Codes: `queue_unavailable` (a background job could not be enqueued; retry the call), `billing_unavailable` (Stripe would not open a checkout session; nothing was charged, retry the call), `service_unavailable` (the rate-limit store is down, so the request was refused before running).

---

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