> ## Documentation Index > Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get escrow recovery report > Requires the `settlements:read` scope (as an M2M scope or a user permission). Report what KeyStone recorded for the settlement beside what the escrow contract reports at one block: status, the chain deadline, each leg's deposit and refund flags, whether claimTimeout or claimRefund would be accepted at that block, and who the contract accepts those claims from. Evidence the deployment cannot obtain is reported as not_configured or unavailable, never resolved optimistically. Read-only: nothing is submitted, no state changes, and KeyStone keeps no record of claims others submit. Readable by the administering environment and every participant grant. Served with Cache-Control: private, no-store. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/settlements/{settlement_id}/recovery openapi: 3.1.0 info: title: Keystone API description: Settlement orchestration API for tokenized Real-World Assets (RWAs). version: 0.9.0 x-keystone-api-contract-version: 0.9.0 x-keystone-source-revision: c094c5ec38de81d550cde98e6366efaac99cffea servers: - url: https://api-staging.keystoneos.xyz description: Staging (sandbox) - url: https://api.keystoneos.xyz description: Production security: - bearerAuth: [] tags: - name: health description: Health and version checks. - name: platforms description: Register and manage your platform profile. - name: environments description: Manage platform environments (sandbox, production). - name: settlement-templates description: View and manage settlement templates. - name: settlements description: Initiate, monitor, and manage settlements. - name: sessions description: Create and manage browser-safe session tokens for frontend widgets. - name: instructions description: Submit and manage settlement instructions. - name: invitations description: Invite team members to your platform. - name: members description: Manage platform team members and roles. - name: webhooks description: Configure webhook endpoints for real-time event notifications. - name: security description: IP allowlisting and API access controls. - name: activity description: Audit trail of platform actions. - name: dashboard description: Dashboard metrics and statistics. - name: callbacks description: Provider callback handlers (internal). - name: alchemy-webhooks description: Alchemy blockchain event webhooks (internal). - name: chains description: Supported blockchain networks for settlement. - name: admin description: KeyStone internal administration endpoints. - name: admin-platforms description: Admin platform management. - name: admin-settlements description: Admin settlement oversight and intervention. - name: admin-compliance description: Admin compliance check management. - name: admin-activity description: Admin system-wide activity logs. - name: admin-webhooks description: Admin webhook diagnostics. - name: internal description: Keystone-internal worker endpoints. - name: internal-compliance description: Internal compliance engine endpoints. paths: /v1/settlements/{settlement_id}/recovery: get: tags: - settlements summary: Get escrow recovery report description: >- Requires the `settlements:read` scope (as an M2M scope or a user permission). Report what KeyStone recorded for the settlement beside what the escrow contract reports at one block: status, the chain deadline, each leg's deposit and refund flags, whether claimTimeout or claimRefund would be accepted at that block, and who the contract accepts those claims from. Evidence the deployment cannot obtain is reported as not_configured or unavailable, never resolved optimistically. Read-only: nothing is submitted, no state changes, and KeyStone keeps no record of claims others submit. Readable by the administering environment and every participant grant. Served with Cache-Control: private, no-store. operationId: get_recovery_report_v1_settlements__settlement_id__recovery_get parameters: - name: settlement_id in: path required: true schema: type: string format: uuid title: Settlement Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RecoveryReportRead' '404': description: Settlement not found. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: RecoveryReportRead: properties: settlement_id: type: string format: uuid title: Settlement Id generated_at: type: string format: date-time title: Generated At recorded: $ref: '#/components/schemas/RecordedExecutionRead' evidence: type: string enum: - observed - not_configured - unavailable title: Evidence description: >- observed when the contract answered; not_configured when this deployment has no contract; unavailable when a declared contract could not be read. unavailable_reason: anyOf: - type: string - type: 'null' title: Unavailable Reason escrow: anyOf: - $ref: '#/components/schemas/ObservedEscrowRead' - type: 'null' legs: items: $ref: '#/components/schemas/RecoveryLegRead' type: array title: Legs description: >- KeyStone's legs in canonical order, each with the contract's view where observed. funds: type: string enum: - unknown - not_registered - none_deposited - held_in_escrow - paid_out - partially_refunded - refunded title: Funds description: >- Where the deposited funds stand as observed; unknown whenever the evidence does not establish it. timeout_claim: $ref: '#/components/schemas/ClaimRead' refund_claims: items: $ref: '#/components/schemas/ClaimRead' type: array title: Refund Claims description: >- One per leg the contract reports deposited; nothing is refundable that was never deposited. claim_submissions: type: string const: unknown title: Claim Submissions claim_submissions_meaning: type: string title: Claim Submissions Meaning actor_meaning: type: string title: Actor Meaning next_steps: items: $ref: '#/components/schemas/RecoveryStepRead' type: array title: Next Steps type: object required: - settlement_id - generated_at - recorded - evidence - unavailable_reason - escrow - legs - funds - timeout_claim - refund_claims - claim_submissions - claim_submissions_meaning - actor_meaning - next_steps title: RecoveryReportRead examples: - actor_meaning: >- claimTimeout and claimRefund are accepted by the contract from the operator or from a wallet recorded as the depositor of a deposited leg of this settlement. Reading this report grants neither; owning or administering the settlement on KeyStone is not either actor. Every refund pays the leg's recorded depositor whoever submits the claim. claim_submissions: unknown claim_submissions_meaning: >- KeyStone keeps no record of claim requests or submissions and never submits one; whether a claim is in flight is unknown here. A claim that lands is observed as a status or refund change at a later block. escrow: chain_timeout_at: 1789556400 deadline_passed_at_block: true deposited_count: 1 leg_count: 2 legs_match_record: true observation: block_hash: 0x5a5a... block_number: 31337000 block_timestamp: 1789560000 chain_id: 84532 escrow_address: '0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512' meaning: >- The contract's answer at this block, the latest the node served when asked. It is an observation, not finality: a later block can differ. observed_at: '2026-09-16T12:00:00Z' raw_status: 1 status: registered evidence: observed funds: held_in_escrow generated_at: '2026-09-16T12:00:00Z' legs: - direction: deliver id: 6f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8 leg_index: 0 observed: amount: '1000' deposited: true depositor: '0x1111111111111111111111111111111111111111' depositor_fees: '0' refund_total: '1000' refunded: false token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' party_role: seller recorded_status: locked next_steps: - action: claim_timeout actor: >- the contract operator or a wallet recorded as the depositor of a deposited leg description: >- Call claimTimeout(settlementId) on the escrow; the contract moves the settlement to TimedOut. recorded: deadline_passed: true escrow_chain_id: 84532 machine_version: dvp/v1 state: AWAITING_DEPOSITS timeout_at: '2026-09-16T11:00:00Z' refund_claims: [] settlement_id: 550e8400-e29b-41d4-a716-446655440000 timeout_claim: actor: >- the contract operator or a wallet recorded as the depositor of a deposited leg available: true basis: >- The escrow is Registered and the observed block is at or past timeoutAt. method: claimTimeout HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail code: type: string enum: - VALIDATION_ERROR title: Code docs_url: type: string title: Docs Url examples: - https://docs.keystoneos.xyz/guides/error-codes#validation-error type: object title: HTTPValidationError required: - detail - code - docs_url RecordedExecutionRead: properties: state: type: string title: State description: The machine state KeyStone recorded. machine_version: type: string title: Machine Version timeout_at: type: string format: date-time title: Timeout At description: The stored escrow deadline. deadline_passed: type: boolean title: Deadline Passed description: >- Whether timeout_at lies at or before generated_at, by KeyStone's clock. escrow_chain_id: anyOf: - type: integer - type: 'null' title: Escrow Chain Id description: >- The chain KeyStone recorded the registration on; null when none was recorded. type: object required: - state - machine_version - timeout_at - deadline_passed - escrow_chain_id title: RecordedExecutionRead ObservedEscrowRead: properties: status: type: string title: Status description: >- The contract's status resolved: none, registered, executed, aborted, timed_out, or unknown for a status this deployment cannot map. raw_status: type: integer title: Raw Status chain_timeout_at: type: integer title: Chain Timeout At description: The contract's timeoutAt, in Unix seconds. deadline_passed_at_block: type: boolean title: Deadline Passed At Block description: >- Whether the observed block's timestamp is at or past chain_timeout_at. leg_count: type: integer title: Leg Count deposited_count: type: integer title: Deposited Count legs_match_record: type: boolean title: Legs Match Record description: Whether the contract's leg count equals the legs KeyStone recorded. observation: $ref: '#/components/schemas/EscrowObservationRead' type: object required: - status - raw_status - chain_timeout_at - deadline_passed_at_block - leg_count - deposited_count - legs_match_record - observation title: ObservedEscrowRead RecoveryLegRead: properties: id: type: string format: uuid title: Id leg_index: type: integer title: Leg Index party_role: type: string title: Party Role direction: type: string title: Direction recorded_status: type: string title: Recorded Status description: The leg status KeyStone recorded. observed: anyOf: - $ref: '#/components/schemas/ObservedLegRead' - type: 'null' description: >- The contract's view at the observed block; null when unobserved or when the contract's leg count differs from KeyStone's. type: object required: - id - leg_index - party_role - direction - recorded_status - observed title: RecoveryLegRead ClaimRead: properties: method: type: string enum: - claimTimeout - claimRefund title: Method leg_index: anyOf: - type: integer - type: 'null' title: Leg Index leg_id: anyOf: - type: string format: uuid - type: 'null' title: Leg Id available: anyOf: - type: boolean - type: 'null' title: Available description: >- Whether the contract would accept the claim at the observed block; null when that cannot be established. actor: type: string title: Actor description: Who the contract accepts the claim from. basis: type: string title: Basis description: The contract rule and observed fact behind available. payee: anyOf: - type: string - type: 'null' title: Payee description: For claimRefund, the recorded depositor the refund pays. amount: anyOf: - type: string - type: 'null' title: Amount description: For claimRefund, amount plus depositor_fees. type: object required: - method - leg_index - leg_id - available - actor - basis - payee - amount title: ClaimRead RecoveryStepRead: properties: action: type: string enum: - establish_evidence - wait - claim_timeout - claim_refund - none title: Action leg_index: anyOf: - type: integer - type: 'null' title: Leg Index actor: anyOf: - type: string - type: 'null' title: Actor description: type: string title: Description type: object required: - action - leg_index - actor - description title: RecoveryStepRead ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError EscrowObservationRead: properties: chain_id: type: integer title: Chain Id description: The chain the observed contract is bound on. escrow_address: type: string title: Escrow Address description: The KeystoneSettlement contract that answered. block_number: type: integer title: Block Number block_hash: type: string title: Block Hash block_timestamp: type: integer title: Block Timestamp description: >- The observed block's timestamp, in Unix seconds; the clock the contract's deadline is judged against. observed_at: type: string format: date-time title: Observed At description: When KeyStone took the observation, by its own clock. meaning: type: string title: Meaning type: object required: - chain_id - escrow_address - block_number - block_hash - block_timestamp - observed_at - meaning title: EscrowObservationRead ObservedLegRead: properties: token: type: string title: Token amount: type: string title: Amount description: The registered leg amount, in base units. depositor_fees: type: string title: Depositor Fees description: >- The additive fee registered on the leg; refunded to the depositor with the amount. refund_total: type: string title: Refund Total description: 'amount plus depositor_fees: what claimRefund pays.' deposited: type: boolean title: Deposited refunded: type: boolean title: Refunded description: >- The contract's refunded flag at the observed block: evidence at that block, not independent finality. depositor: anyOf: - type: string - type: 'null' title: Depositor description: The wallet recorded as depositor; null until deposited. type: object required: - token - amount - depositor_fees - refund_total - deposited - refunded - depositor title: ObservedLegRead securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Auth0 JWT access token. See [Authentication](/getting-started/authentication) for details. ````