FOformancehq
Ledgers

List all ledgers

Changed on

Lists the ledgers in the cluster, paged by name (ascending unless reverse=true). Requires ledger:read scope.

get/v3/

Request

  • Base URL
    http://localhost:9000
  • URL
    http://localhost:9000/v3/
  • Auth
    • HTTP bearer
    • or none

Query parameters

pageSizeinteger

Maximum number of items per page. 0 or absent means 100; values above 1000 are clamped to 1000.

cursorstring

Page token of a paged list. Clients normally pass back the next or previous value of a previous response verbatim; building one by hand is supported.

A token is base64url (unpadded, RFC 4648 §5) of the JSON object {"key": <string>, "back": <bool>}. Both fields are omitted when empty, and unknown fields are rejected. key is a position in the endpoint's textual form:

  • transactions: decimal transaction id
  • logs: decimal ledger-local log id
  • audit entries: decimal audit sequence
  • accounts: address
  • ledgers and numscripts: name
  • signing keys: key id
  • prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS
  • index inspection: base64url of the encoded metadata value

Both directions exclude the key and return rows in the requested order (reverse included):

  • {"key": K} serves the rows strictly after K;
  • {"key": K, "back": true} serves the page that ends strictly before K;
  • {"back": true} serves the last page;
  • an absent or empty token, or e30 ({}), serves the first page.

On a forward page, next is set when a further row follows the page, and previous whenever the request carried a key. On a back page, previous is set when a further row precedes the page, and next whenever the request carried a key. A first page therefore has no previous, and the last page requested with {"back": true} has no next. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 INVALID_REQUEST.

Page token from a previous response's next or previous field (see the PageToken schema). Omit for the first page. Pass the same reverse and filter on every page of a walk.

reverseboolean

List in descending name order when true.

Headers

X-Consistency'linearizable' | 'stale'

Read consistency. linearizable (the default) runs a Raft ReadIndex barrier and waits for the receiving node to apply up to it. stale serves the read from the receiving node's own store, with no barrier and no forwarding to the leader, so the answer may lag the leader. Matching ignores case and surrounding whitespace. An unknown value, or a repeated or comma-joined header, returns 400 INVALID_REQUEST on every /v3 route, writes included; a valid value has no effect on writes. The gRPC equivalent is the x-consistency request metadata.

Response

List of ledgers retrieved successfully

nextstring

Page token of a paged list. Clients normally pass back the next or previous value of a previous response verbatim; building one by hand is supported.

A token is base64url (unpadded, RFC 4648 §5) of the JSON object {"key": <string>, "back": <bool>}. Both fields are omitted when empty, and unknown fields are rejected. key is a position in the endpoint's textual form:

  • transactions: decimal transaction id
  • logs: decimal ledger-local log id
  • audit entries: decimal audit sequence
  • accounts: address
  • ledgers and numscripts: name
  • signing keys: key id
  • prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS
  • index inspection: base64url of the encoded metadata value

Both directions exclude the key and return rows in the requested order (reverse included):

  • {"key": K} serves the rows strictly after K;
  • {"key": K, "back": true} serves the page that ends strictly before K;
  • {"back": true} serves the last page;
  • an absent or empty token, or e30 ({}), serves the first page.

On a forward page, next is set when a further row follows the page, and previous whenever the request carried a key. On a back page, previous is set when a further row precedes the page, and next whenever the request carried a key. A first page therefore has no previous, and the last page requested with {"back": true} has no next. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 INVALID_REQUEST.

previousstring

Page token of a paged list. Clients normally pass back the next or previous value of a previous response verbatim; building one by hand is supported.

A token is base64url (unpadded, RFC 4648 §5) of the JSON object {"key": <string>, "back": <bool>}. Both fields are omitted when empty, and unknown fields are rejected. key is a position in the endpoint's textual form:

  • transactions: decimal transaction id
  • logs: decimal ledger-local log id
  • audit entries: decimal audit sequence
  • accounts: address
  • ledgers and numscripts: name
  • signing keys: key id
  • prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS
  • index inspection: base64url of the encoded metadata value

Both directions exclude the key and return rows in the requested order (reverse included):

  • {"key": K} serves the rows strictly after K;
  • {"key": K, "back": true} serves the page that ends strictly before K;
  • {"back": true} serves the last page;
  • an absent or empty token, or e30 ({}), serves the first page.

On a forward page, next is set when a further row follows the page, and previous whenever the request carried a key. On a back page, previous is set when a further row precedes the page, and next whenever the request carried a key. A first page therefore has no previous, and the last page requested with {"back": true} has no next. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 INVALID_REQUEST.

hasMoreboolean required

True when a following page exists; set iff next is.

Changes

  • f5e817eca038Revision changes
    • info

      api operation id listAllLedgers removed and replaced with v3ListAllLedgers

  • 45c54ddbb457Revision changes
    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      the response property // became required for the status

    • info

      added the required property // to the response with the status