---
title: "Run one ledger recovery action"
method: POST
path: "/v1/token-accounting/recover"
tags: ["System"]
---

# Run one ledger recovery action

`POST /v1/token-accounting/recover`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/token-accounting/recover`
- Auth: HTTP bearer

Runs one recovery action and answers with the report it left behind. `reopen` retries an unavailable store; `retryNonDurable` retries observations held after a failed write; `rebuildProjections` recomputes every session projection from its committed attempts; `compact` trims retained observations and the change outbox to their bounds; `reprice` prices final attempts whose money is unknown for lack of a rate, from the compiled price list, and never touches an attempt that has an amount. None invents accounting evidence. Requires tools:exec.

## Request body

- object
  - `action` 'reopen' | 'retryNonDurable' | 'rebuildProjections' | 'compact' | 'reprice', required

## Response `200`

Recovery outcome and report

- TokenLedgerRecoveryResult
  - `action` 'reopen' | 'retryNonDurable' | 'rebuildProjections' | 'compact' | 'reprice', required
  - `succeeded` boolean, required
  - `affected` integer, nullable
  - `report` TokenAccountingHealthReport, required: Bounded local health metrics for the accounting system (shared contract shared/types/contracts/token-accounting.ts). `counting` is null when no pinned counting service is installed.
    - `observedAt` string, date-time, required
    - `ledger` TokenLedgerOperability, required
      - `health` TokenLedgerHealth, required: Store-wide accounting health (shared contract shared/types/contracts/token-accounting.ts). `degraded` means a write failed and observations are held in memory; `unavailable` means the store could not be opened.
        - `state` 'available' | 'degraded' | 'unavailable', required
        - `fault` 'busy' | 'diskFull' | 'permissionDenied' | 'corrupt' | 'migrationFailed' | 'ownedByAnotherProcess' | 'ioError', nullable
        - `nonDurableObservations` integer, required
        - `suppressedObservations` integer, required
        - `quarantinedAttempts` integer, required
        - `unresolvedAttempts` integer, required
        - `oldestUnresolvedAt` string, date-time, nullable
      - `storeId` string, nullable
      - `ledgerRevision` integer, required
      - `usageCoverage` TokenUsageCoverage, required: Terminal attempts by usage availability — the coverage denominator. An attempt that never sent is counted apart.
        - `terminalAttempts` integer, required
        - `complete` integer, required
        - `partial` integer, required
        - `missing` integer, required
        - `invalid` integer, required
        - `mismatch` integer, required
        - `unsupported` integer, required
        - `neverDispatched` integer, required
      - `mismatchedAttempts` integer, required
      - `reconciliationBacklog` integer, required
      - `oldestUnresolvedAgeSeconds` number, nullable
      - `writeFailures` integer, required
      - `lostNonDurableObservations` integer, required
      - `rejectedObservations` integer, required
      - `committedBatches` integer, required
      - `queueWait` TokenLatencyDigest, required: A latency distribution over a bounded reservoir of the most recent samples (shared contract shared/types/contracts/token-accounting.ts). Milliseconds; percentiles are null while the reservoir is empty.
        - `samples` integer, required
        - `recorded` integer, required
        - `p50Ms` number, nullable
        - `p95Ms` number, nullable
        - `p99Ms` number, nullable
        - `maxMs` number, nullable
      - `commitLatency` TokenLatencyDigest, required: A latency distribution over a bounded reservoir of the most recent samples (shared contract shared/types/contracts/token-accounting.ts). Milliseconds; percentiles are null while the reservoir is empty.
        - `samples` integer, required
        - `recorded` integer, required
        - `p50Ms` number, nullable
        - `p95Ms` number, nullable
        - `p99Ms` number, nullable
        - `maxMs` number, nullable
    - `counting` TokenCountingOperability
      - `loadedHandles` integer, required
      - `cachedCounts` integer, required
      - `loadsStarted` integer, required
      - `cacheHits` integer, required
      - `cacheMisses` integer, required
      - `activeCounts` integer, required
      - `queuedCounts` integer, required
      - `refusals` object, required
      - `unsupportedContracts` integer, required
      - `presetSupport` object, required
        - `supported` integer, required
        - `candidate` integer, required
        - `unsupported` integer, required
      - `coldLoad` TokenLatencyDigest, required: A latency distribution over a bounded reservoir of the most recent samples (shared contract shared/types/contracts/token-accounting.ts). Milliseconds; percentiles are null while the reservoir is empty.
        - `samples` integer, required
        - `recorded` integer, required
        - `p50Ms` number, nullable
        - `p95Ms` number, nullable
        - `p99Ms` number, nullable
        - `maxMs` number, nullable
      - `warmCount` TokenLatencyDigest, required: A latency distribution over a bounded reservoir of the most recent samples (shared contract shared/types/contracts/token-accounting.ts). Milliseconds; percentiles are null while the reservoir is empty.
        - `samples` integer, required
        - `recorded` integer, required
        - `p50Ms` number, nullable
        - `p95Ms` number, nullable
        - `p99Ms` number, nullable
        - `maxMs` number, nullable
      - `queueWait` TokenLatencyDigest, required: A latency distribution over a bounded reservoir of the most recent samples (shared contract shared/types/contracts/token-accounting.ts). Milliseconds; percentiles are null while the reservoir is empty.
        - `samples` integer, required
        - `recorded` integer, required
        - `p50Ms` number, nullable
        - `p95Ms` number, nullable
        - `p99Ms` number, nullable
        - `maxMs` number, nullable

## Other responses

- `400`: Unknown action

---

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