---
title: "Get the caller's credit-transaction history."
method: GET
path: "/mcp/credits/ledger"
tags: ["credits"]
---

# Get the caller's credit-transaction history.

`GET /mcp/credits/ledger`

## Request

- Base URL: `https://api.prosp.cc`
- URL: `https://api.prosp.cc/mcp/credits/ledger`
- Auth: OAuth 2 (client credentials, token URL `https://prosp-mcp-641053169627.auth.eu-central-1.amazoncognito.com/oauth2/token`, scopes: `mcp/execute`)

Returns the authenticated customer's credit transactions — debits (discovery-job charges),
refunds, and manual adjustments — newest first, reconstructed from durable job and refund
markers. EVERY row carries a signed `amount` in credits, so a client can `sum(amount)` to
reconcile the ledger against `balance`. `limit` bounds the number of TRANSACTIONS returned
(a single job can contribute up to two rows — a debit and its refund) and `offset` selects a
stable page; `total` + `has_more` let a client walk the full reconstructable history. The
ledger is a BOUNDED WINDOW: markers older than `window_start` (≈7 days) have expired and can
no longer be reconstructed — `history_incomplete=true` signals such older history exists
(`truncated` is a separate this-page hard-cap signal, always false here).

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

The caller's credit-transaction history.

- CreditLedger: A customer's credit-transaction history (`GET /mcp/credits/ledger`). Every transaction row carries a signed `amount`, so `sum(transactions[].amount)` reconciles the credit movement against `balance`.
  - `customer_id` string, required: The authenticated customer these transactions belong to.
  - `balance` integer, required: Current credit balance.
  - `count` integer, required: Number of transactions in THIS page (never exceeds the requested `limit`).
  - `total` integer, required: Total reconstructable transactions in the window (across all pages). When `history_incomplete` is true this is a lower bound — older, marker-expired history is not counted.
  - `offset` integer, required: The starting index this page was served from (echoes the request `offset`, clamped to `total`).
  - `has_more` boolean, required: True when this page left transactions unreturned — fetch the next page with `offset += count`.
  - `window_start` string, date-time, required: RFC-3339 UTC start of the reconstructable window (`now − marker TTL`, ≈7 days). Transactions older than this have expired markers and cannot be reconstructed.
  - `truncated` boolean, required: PURE this-page hard-cap signal: true only when an item/byte cap dropped rows from THIS page. The ledger paginates on `offset`/`limit` with no per-page item/byte cap (`has_more` covers the tail), so `truncated` is always `false` here. Retained for a uniform pagination envelope across list surfaces. The "older history exists" signal is the DISTINCT `history_incomplete` field below — do NOT read `truncated` for data completeness.
  - `history_incomplete` boolean, required: Data-COMPLETENESS signal (distinct from `truncated`): true when older account history exists that the bounded markers can no longer reconstruct — set in exactly two cases: (1) the customer has more jobs than a single read enumerates (only the newest are scanned), or (2) a job's paired debit/refund fell outside the reconstructable window so one half-pair row was suppressed. When true, the visible rows are still internally consistent but do NOT span the customer's whole account history. A COMPLETE page (`has_more=false`, `count == total`) can still be `history_incomplete=true` — the two flags are orthogonal.
  - `transactions` LedgerTransaction[], required: Credit transactions, newest first.
    - `type` 'debit' | 'refund' | 'adjustment', required: `debit` = a discovery-job charge; `refund` = credits returned for a terminated/refunded job; `adjustment` = a manual balance change.
    - `job_id` string: The discovery job this row belongs to. Absent on manual adjustments.
    - `icp_id` string: The saved ICP this charge is attributable to — the `icpId` the run was started with via `POST /api/v1/discoveries {"icpId": ...}`. Lets a customer running several saved ICPs reconcile a charge back to the ICP that caused it. Carried on both the `debit` row and its paired `refund` row, so an attribution survives the two landing on different pages. ABSENT (field omitted, never an empty string) for an ad-hoc run started from inline criteria, and on `adjustment` rows, which have no job. Ids are scoped to the calling customer — the same namespace `GET /api/v1/icps` returns.
    - `amount` integer, required: Signed credit movement — negative for a debit, positive for a refund/grant.
    - `reason` string, required: Bounded reason for the movement (e.g. `discovery_job`, `candidates_exhausted`, `time_limit_reached`, `manual_reconciliation`).
    - `balance_after` integer, nullable: Best-effort: the TRUE balance immediately after this event, present ONLY when a durable post-event snapshot was recorded at the source (`jobs:charged-balance:{jobId}`, written by the gateway debit script). OMITTED (field absent) on rows with no snapshot — historical debits that predate the snapshot feature, and reconstructed/inferred refunds — because a running balance is NOT reliably reconstructable after the fact (concurrent jobs and top-ups make back-derivation unsound). Never fabricated: a null/absent value means "unknown", not zero. Reconcile via the signed `amount` column, which every row carries.
    - `timestamp` string, date-time, required: RFC-3339 UTC timestamp (…Z) of the transaction.
    - `adjustment_id` string: Audit id of a manual adjustment (adjustment rows only).
    - `actor` string: Who performed a manual adjustment (adjustment rows only).

## Other responses

- `401`: Missing/invalid/expired Bearer token.
- `405`: HTTP method not allowed on this endpoint (rejected before any credit debit).
- `429`: Rate limit exceeded (100 requests / 60s per customer).

---

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