> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List cautionary blocks > Lists the cautionary blocks of your institution, oldest update first. Filter by `origin_system`, `status` (repeatable), `updated_before` and `external_ref`. The list uses cursor pagination: pass `next_cursor` as `cursor` to read the next page; `next_cursor` is `null` on the last page. `limit` defaults to 20 and is at most 100. A non-integer `limit` is refused with `400` (`PIX-0020`). The `status` of a lock tells which operation applies. A `PENDING` lock can be settled, released or closed. A `SETTLING` lock waits for the confirmation of its settlement, and one whose devolution failed can also be closed. An `AWAITING_CREDIT` lock waits for the parked credit of its Pix and can only be released. ## OpenAPI ````yaml /en/openapi/v3-current/pix-lerian-spi.yaml get /balance-locks openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.2.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences - description: >- Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks paths: /balance-locks: get: tags: - Balance Locks summary: List cautionary blocks description: >- Lists the cautionary blocks of your institution, oldest update first. Filter by `origin_system`, `status` (repeatable), `updated_before` and `external_ref`. The list uses cursor pagination: pass `next_cursor` as `cursor` to read the next page; `next_cursor` is `null` on the last page. `limit` defaults to 20 and is at most 100. A non-integer `limit` is refused with `400` (`PIX-0020`). The `status` of a lock tells which operation applies. A `PENDING` lock can be settled, released or closed. A `SETTLING` lock waits for the confirmation of its settlement, and one whose devolution failed can also be closed. An `AWAITING_CREDIT` lock waits for the parked credit of its Pix and can only be released. operationId: listBalanceLocks parameters: - description: >- Scope of the calling consumer (e.g. med-infraction). Omit to list across every origin_system. explode: false in: query name: origin_system schema: description: >- Scope of the calling consumer (e.g. med-infraction). Omit to list across every origin_system. type: string - description: >- Filter by status (repeatable): PENDING, SETTLING, RELEASED, SETTLED, AWAITING_CREDIT explode: true in: query name: status schema: description: >- Filter by status (repeatable): PENDING, SETTLING, RELEASED, SETTLED, AWAITING_CREDIT examples: - - PENDING items: type: string type: - array - 'null' - description: Only balance locks with updated_at before this RFC 3339 timestamp explode: false in: query name: updated_before schema: description: Only balance locks with updated_at before this RFC 3339 timestamp type: string - description: Restrict to a single grouping operation explode: false in: query name: external_ref schema: description: Restrict to a single grouping operation type: string - description: Page size (1-100, default 20) explode: false in: query name: limit schema: description: Page size (1-100, default 20) examples: - '20' type: string - description: Opaque cursor returned by the previous page explode: false in: query name: cursor schema: description: Opaque cursor returned by the previous page type: string responses: '200': content: application/json: example: items: - lock_id: 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 origin_system: med-infraction external_ref: med-2026-000123 end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 status: PENDING requested_amount: '150.75' effective_amount: '100.26' settled_amount: null payment_type: null pix_end_to_end_id: null settling_at: null surplus_midaz_tx_id: null created_at: '2026-10-27T10:41:07Z' updated_at: '2026-10-27T10:41:07Z' - lock_id: 01a17cf5-983a-7d13-a4c8-2e9f51b06d37 origin_system: med-infraction external_ref: med-2026-000123 end_to_end_id: E12345678202610271032k7Qm2Xp9Ld4 status: PENDING requested_amount: '50.49' effective_amount: '50.49' settled_amount: null payment_type: null pix_end_to_end_id: null settling_at: null surplus_midaz_tx_id: null created_at: '2026-10-27T10:43:52Z' updated_at: '2026-10-27T10:43:52Z' next_cursor: null schema: $ref: '#/components/schemas/ListBalanceLocksOutput' description: OK '400': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0003 title: Bad Request status: 400 detail: >- Your request contains one or more fields with an invalid data type. code: PIX-0003 schema: $ref: '#/components/schemas/Detail' description: >- An unknown status, an updated_before that is not RFC 3339 (PIX-0003), or a non-integer limit (PIX-0020). '500': content: application/json: example: code: PIX-0000 title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: >- The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: ListBalanceLocksOutput: additionalProperties: false properties: items: items: $ref: '#/components/schemas/BalanceLockListItem' type: - array - 'null' next_cursor: type: - string - 'null' required: - items - next_cursor type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object BalanceLockListItem: additionalProperties: false properties: created_at: examples: - '2026-10-27T10:41:07Z' format: date-time type: string effective_amount: examples: - '100.26' type: string end_to_end_id: examples: - E12345678202610271032k7Qm2Xp9Ld4 type: string external_ref: examples: - med-2026-000123 type: string lock_id: examples: - 01a17cf3-128e-7c41-9b2e-5d7a3f8c1e60 type: string origin_system: examples: - med-infraction type: string payment_type: type: - string - 'null' pix_end_to_end_id: type: - string - 'null' requested_amount: examples: - '150.75' type: string settled_amount: type: - string - 'null' settling_at: format: date-time type: - string - 'null' status: examples: - PENDING type: string surplus_midaz_tx_id: type: - string - 'null' updated_at: examples: - '2026-10-27T10:41:07Z' format: date-time type: string required: - lock_id - origin_system - external_ref - end_to_end_id - status - requested_amount - effective_amount - created_at - updated_at type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.