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

# List Credit Ledger

> Page through the credit transaction history: top-ups, escrow holds, hold releases, captures, refunds, and adjustments.

Lists every [credit](/docs/developers/concepts/credits-and-billing) ledger entry on your account, newest first, with cursor pagination. Each entry links the related top-up, proposal, contract, or milestone so you can reconcile balance changes against the actions that caused them.

`amountCents` is signed: positive entries add to the available balance, negative entries draw from it. Accounts that have never used credits get an empty page (not a `404`).

**Requirements:** `payments:read` scope + the `public_api_credits` feature. Works pre-claim.

## Entry types

| `type`         | Meaning                                                                                             |
| -------------- | --------------------------------------------------------------------------------------------------- |
| `TOP_UP`       | A completed [top-up](/docs/developers/api-reference/credits/create-top-up) added funds                   |
| `HOLD`         | Funds reserved into escrow (hire or [milestone funding](/docs/developers/api-reference/milestones/fund)) |
| `HOLD_RELEASE` | A hold returned to the available balance (e.g. milestone cancelled)                                 |
| `CAPTURE`      | Held funds paid out (milestone released)                                                            |
| `REFUND`       | Funds returned to the account                                                                       |
| `ADJUSTMENT`   | Manual correction by OpenTrain                                                                      |

## Request

<ParamField query="cursor" type="string">
  Opaque cursor from a previous response's `nextCursor`. Omit for the first page.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Page size, 1–100. Out-of-range values return `400`.
</ParamField>

## Response

<ResponseField name="entries" type="object[]">
  <Expandable title="ledger entry">
    <ResponseField name="id" type="string">
      Ledger entry ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      One of the entry types above.
    </ResponseField>

    <ResponseField name="amountCents" type="number">
      Signed amount in US cents.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp.
    </ResponseField>

    <ResponseField name="holdEntryId" type="string | null">
      For `HOLD_RELEASE`/`CAPTURE`, the originating `HOLD` entry.
    </ResponseField>

    <ResponseField name="jobofferId" type="string | null">
      Related proposal, when the entry came from a hire.
    </ResponseField>

    <ResponseField name="contractId" type="string | null">
      Related contract.
    </ResponseField>

    <ResponseField name="milestoneId" type="string | null">
      Related milestone.
    </ResponseField>

    <ResponseField name="topUpId" type="string | null">
      Related top-up, for `TOP_UP` entries.
    </ResponseField>

    <ResponseField name="note" type="string | null">
      Free-text note (mostly on `ADJUSTMENT` entries).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Pass as `cursor` to fetch older entries; `null` at the end of the ledger.
</ResponseField>

## Errors

| Status | `code`         | Meaning                                                         |
| ------ | -------------- | --------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`  | `limit` outside 1–100 (`details: {field: "limit"}`)             |
| `401`  | `UNAUTHORIZED` | Missing or invalid token                                        |
| `403`  | `FORBIDDEN`    | Missing `payments:read` scope, or `public_api_credits` disabled |

<RequestExample>
  ```bash curl theme={null}
  curl -sS "https://app.opentrain.ai/api/public/v1/credits/ledger?limit=25" \
    -H "Authorization: Bearer $OT_API_TOKEN"
  ```

  ```bash CLI theme={null}
  opentrain credits ledger --limit 25 --json
  ```

  ```json MCP: opentrain_list_credit_ledger theme={null}
  {
    "limit": 25
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "entries": [
      {
        "id": "<ENTRY_ID>",
        "type": "TOP_UP",
        "amountCents": 10000,
        "createdAt": "2026-06-12T10:00:00.000Z",
        "holdEntryId": null,
        "jobofferId": null,
        "contractId": null,
        "milestoneId": null,
        "topUpId": "<TOP_UP_ID>",
        "note": null
      },
      {
        "id": "<ENTRY_ID_2>",
        "type": "HOLD",
        "amountCents": -2500,
        "createdAt": "2026-06-11T15:30:00.000Z",
        "holdEntryId": null,
        "jobofferId": "<PROPOSAL_ID>",
        "contractId": "<CONTRACT_ID>",
        "milestoneId": "<MILESTONE_ID>",
        "topUpId": null,
        "note": null
      }
    ],
    "nextCursor": "<CURSOR>"
  }
  ```
</ResponseExample>