Read a page of ledger's filtered updates

POST /v2/updates/get-updates-page

Request

curl --request POST \
  --url 'http://localhost:7575/v2/updates/get-updates-page' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"beginOffsetExclusive":0,"endOffsetInclusive":0,"maxPageSize":0,"updateFormat":{"includeTransactions":{},"includeReassignments":{},"includeTopologyEvents":{}},"descendingOrder":false,"pageToken":"string"}'

200 response

{
  "updates": [
    {}
  ],
  "lowestPageOffsetExclusive": 0,
  "highestPageOffsetInclusive": 0,
  "nextPageToken": "string"
}

JSON Ledger API

Read a page of ledger’s filtered updates

OpenAPISince 3.5

Read a page of ledger’s filtered updates. It returns the event types in accordance with the specified contents and filters. Additionally, the selection criteria for individual events depends on the transaction shape chosen. - ACS delta: an event is included only if the requesting party is a stakeholder. - ledger effects: an event is included if the requesting party is a witness.

Protocol Details

Inputs

Request body

application/json

beginOffsetExclusive · number

OpenAPI type: integer (int64).

Exclusive lower bound offset of the requested ledger section (non-negative integer). The response page will only contain updates whose offset is strictly greater than this. If set to zero or not defined, the lower bound is set to the actual pruning offset or to the beginning of the ledger if the participant was not pruned yet. If set to positive and the ledger has been pruned, this parameter must be greater or equal than the pruning offset. Optional

endOffsetInclusive · number

OpenAPI type: integer (int64).

Inclusive upper bound offset of the requested ledger section. If specified the response will only contain updates whose offset is less than or equal to this. If not specified response will only contain updates whose offset is less than the current ledger-end. Optional

maxPageSize · number

OpenAPI type: integer (int32).

The result page will contain the first max_page_size Updates of all matching updates. The server may reject queries with max_page_size above server specified limits. If not specified, the default max_page_size is determined by the server. Optional

updateFormat · object · required

OpenAPI type: UpdateFormat.

A format specifying what updates to include and how to render them.

descendingOrder · boolean

If set, the page will populate the elements in descending order starting from the end_offset_inclusive. Optional

pageToken · string

To get the next page of updates, the page_token should be set to the next_page_token of the last GetUpdatesPageResponse. To achieve correct paging: subsequent requests must - be executed on the same participant, - have the same begin_offset_exclusive, - have the same end_offset_inclusive, - have the same update_format and - have the same descending_order. If not specified, the first page of updates will be returned. Optional: can be empty

Outputs

200

application/json

updates · JsGetUpdateResponse[]

The first max_page_size updates that match the filter in the request. In case descending_order was selected, the order of the updates is in reversed offset order. Optional: can be empty

lowestPageOffsetExclusive · integer (int64) · required

Represents the lower bound of this page. Required

highestPageOffsetInclusive · integer (int64) · required

Represents the upper bound of the page. Required

nextPageToken · string

If the value is not populated, this is the last page. If the value is populated, this token can be used to get the next page. If the original GetFirstUpdatePageRequest end_offset_inclusive was not specified and the request uses ascending order, then this token will always be populated, so you can use it to “tail” the ledger by repeatedly polling with the new page token returned. Optional: can be empty

400

text/plain

value · string · required

default

application/json

code · string · required

cause · string · required

correlationId · string

traceId · string

context · Map_String · required

resources · Tuple2_String_String[]

errorCategory · integer (int32) · required

grpcCodeValue · integer (int32)

retryInfo · string

definiteAnswer · boolean

History

Introduced3.5

Request

curl --request POST \
  --url 'http://localhost:7575/v2/updates/get-updates-page' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"beginOffsetExclusive":0,"endOffsetInclusive":0,"maxPageSize":0,"updateFormat":{"includeTransactions":{},"includeReassignments":{},"includeTopologyEvents":{}},"descendingOrder":false,"pageToken":"string"}'

200 response

{
  "updates": [
    {}
  ],
  "lowestPageOffsetExclusive": 0,
  "highestPageOffsetInclusive": 0,
  "nextPageToken": "string"
}