--- title: "POST /v2/updates/get-updates-page" method: POST path: "/v2/updates/get-updates-page" --- # POST /v2/updates/get-updates-page `POST /v2/updates/get-updates-page` 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. ## Request body - GetUpdatesPageRequest - `beginOffsetExclusive` integer — 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` integer — 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` integer — 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` UpdateFormat, required — A format specifying what updates to include and how to render them. - `includeTransactions` TransactionFormat — A format that specifies what events to include in Daml transactions and what data to compute and include for them. - `eventFormat` EventFormat, required — A format for events which defines both which events should be included and what data should be computed and included for them. Note that some of the filtering behavior depends on the `TransactionShape`, which is expected to be specified alongside usages of `EventFormat`. - `filtersByParty` MapFilters - `filtersForAnyParty` Filters — The union of a set of template filters, interface filters, or a wildcard. - `cumulative` CumulativeFilter[] — Every filter in the cumulative list expands the scope of the resulting stream. Each interface, template or wildcard filter means additional events that will match the query. The impact of include_interface_view and include_created_event_blob fields in the filters will also be accumulated. A template or an interface SHOULD NOT appear twice in the accumulative field. A wildcard filter SHOULD NOT be defined more than once in the accumulative field. If no ``CumulativeFilter`` defined, the default of a single ``WildcardFilter`` with include_created_event_blob unset is used. Optional: can be empty - `identifierFilter` union — Required - … - `verbose` boolean — If enabled, values served over the API will contain more information than strictly necessary to interpret the data. In particular, setting the verbose flag to true triggers the ledger to include labels for record fields. Optional - `transactionShape` 'TRANSACTION_SHAPE_UNSPECIFIED' | 'TRANSACTION_SHAPE_ACS_DELTA' | 'TRANSACTION_SHAPE_LEDGER_EFFECTS', required — What transaction shape to use for interpreting the filters of the event format. Required - `includeReassignments` EventFormat — A format for events which defines both which events should be included and what data should be computed and included for them. Note that some of the filtering behavior depends on the `TransactionShape`, which is expected to be specified alongside usages of `EventFormat`. - `filtersByParty` MapFilters - `filtersForAnyParty` Filters — The union of a set of template filters, interface filters, or a wildcard. - `cumulative` CumulativeFilter[] — Every filter in the cumulative list expands the scope of the resulting stream. Each interface, template or wildcard filter means additional events that will match the query. The impact of include_interface_view and include_created_event_blob fields in the filters will also be accumulated. A template or an interface SHOULD NOT appear twice in the accumulative field. A wildcard filter SHOULD NOT be defined more than once in the accumulative field. If no ``CumulativeFilter`` defined, the default of a single ``WildcardFilter`` with include_created_event_blob unset is used. Optional: can be empty - `identifierFilter` union — Required - object - … - object - … - object - … - object - … - `verbose` boolean — If enabled, values served over the API will contain more information than strictly necessary to interpret the data. In particular, setting the verbose flag to true triggers the ledger to include labels for record fields. Optional - `includeTopologyEvents` TopologyFormat — A format specifying which topology transactions to include and how to render them. - `includeParticipantAuthorizationEvents` ParticipantAuthorizationTopologyFormat — A format specifying which participant authorization topology transactions to include and how to render them. - `parties` string[] — List of parties for which the topology transactions should be sent. Empty means: for all parties. Optional: can be empty - `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 ## Response `200` - JsGetUpdatesPageResponse - `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 - `update` union - object - `OffsetCheckpoint` OffsetCheckpoint2, required — OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption. - `value` OffsetCheckpoint1, required — OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption. - `offset` integer, required — The participant's offset, the details of the offset field are described in ``community/ledger-api/README.md``. Must be a valid absolute offset (positive integer). Required - `synchronizerTimes` SynchronizerTime[] — The times associated with each synchronizer at this offset. Optional: can be empty - … - object - `Reassignment` Reassignment, required — Complete view of an on-ledger reassignment. - `value` JsReassignment, required — Complete view of an on-ledger reassignment. - `updateId` string, required — Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in ``value.proto``). Required - `commandId` string — The ID of the command which resulted in this reassignment. Missing for everyone except the submitting party on the submitting participant. Must be a valid LedgerString (as described in ``value.proto``). Optional - `workflowId` string — The workflow ID used in reassignment command submission. Only set if the ``workflow_id`` for the command was set. Must be a valid LedgerString (as described in ``value.proto``). Optional - `offset` integer, required — The participant's offset. The details of this field are described in ``community/ledger-api/README.md``. Must be a valid absolute offset (positive integer). Required - `events` JsReassignmentEvent[], required — The collection of reassignment events. Required: must be non-empty - … - `traceContext` TraceContext - … - `recordTime` string, required — The time at which the reassignment was recorded. The record time refers to the source/target synchronizer for an unassign/assign event respectively. Required - `synchronizerId` string, required — A valid synchronizer id. Identifies the synchronizer that synchronized this Reassignment. Required - `paidTrafficCost` integer — The traffic cost that this participant node paid for the corresponding (un)assignment request. Not set for transactions that were - initiated by another participant - initiated offline via the repair service - processed before the participant started serving traffic cost on the Ledger API - returned as part of a query filtering for a non submitting party Optional - object - `TopologyTransaction` TopologyTransaction, required - `value` JsTopologyTransaction, required - `updateId` string, required — Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in ``value.proto``). Required - `offset` integer, required — The absolute offset. The details of this field are described in ``community/ledger-api/README.md``. It is a valid absolute offset (positive integer). Required - `synchronizerId` string, required — A valid synchronizer id. Identifies the synchronizer that synchronized the topology transaction. Required - `recordTime` string, required — The time at which the changes in the topology transaction become effective. There is a small delay between a topology transaction being sequenced and the changes it contains becoming effective. Topology transactions appear in order relative to a synchronizer based on their effective time rather than their sequencing time. Required - `events` TopologyEvent[], required — A non-empty list of topology events. Required: must be non-empty - … - `traceContext` TraceContext - … - object - `Transaction` Transaction, required — Filtered view of an on-ledger transaction's create and archive events. - `value` JsTransaction, required — Filtered view of an on-ledger transaction's create and archive events. - `updateId` string, required — Assigned by the server. Useful for correlating logs. Must be a valid LedgerString (as described in ``value.proto``). Required - `commandId` string — The ID of the command which resulted in this transaction. Missing for everyone except the submitting party. Must be a valid LedgerString (as described in ``value.proto``). Optional - `workflowId` string — The workflow ID used in command submission. Must be a valid LedgerString (as described in ``value.proto``). Optional - `effectiveAt` string, required — Ledger effective time. Required - `events` Event[], required — The collection of events. Contains: - ``CreatedEvent`` or ``ArchivedEvent`` in case of ACS_DELTA transaction shape - ``CreatedEvent`` or ``ExercisedEvent`` in case of LEDGER_EFFECTS transaction shape Required: must be non-empty - … - `offset` integer, required — The absolute offset. The details of this field are described in ``community/ledger-api/README.md``. It is a valid absolute offset (positive integer). Required - `synchronizerId` string, required — A valid synchronizer id. Identifies the synchronizer that synchronized the transaction. Required - `traceContext` TraceContext - … - `recordTime` string, required — The time at which the transaction was recorded. The record time refers to the synchronizer which synchronized the transaction. Required - `externalTransactionHash` string — For transaction externally signed, contains the external transaction hash signed by the external party. Can be used to correlate an external submission with a committed transaction. Optional: can be empty - `paidTrafficCost` integer — The traffic cost that this participant node paid for the confirmation request for this transaction. Not set for transactions that were - initiated by another participant - initiated offline via the repair service - processed before the participant started serving traffic cost on the Ledger API - returned as part of a query filtering for a non submitting party Optional - `lowestPageOffsetExclusive` integer, required — Represents the lower bound of this page. Required - `highestPageOffsetInclusive` integer, 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 ## Other responses - `400` — Invalid value, Invalid value for: body - `default` --- [API](https://skmtc.dev/canton/apis/json-ledger-api-http-endpoints.md) · [All operations](https://skmtc.dev/canton/apis/json-ledger-api-http-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/canton/json-ledger-api-http-endpoints/revisions/296292e8b8f1/schema)