---
title: "POST /v2/updates"
method: POST
path: "/v2/updates"
---

# POST /v2/updates

`POST /v2/updates`

Read the ledger's filtered update stream for the specified contents and filters.
It returns the event types in accordance with the stream contents selected. Also the selection criteria
for individual events depends on the transaction shape chosen.

- ACS delta: a requesting party must be a stakeholder of an event for it to be included.
- ledger effects: a requesting party must be a witness of an event for it to be included.
Notice: This endpoint should be used for small results set.
When number of results exceeded node configuration limit (`http-list-max-elements-limit`)
there will be an error (`413 Content Too Large`) returned.
Increasing this limit may lead to performance issues and high memory consumption.
Consider using websockets (asyncapi) for better efficiency with larger results.

## Query parameters

- `limit` integer
- `stream_idle_timeout_ms` integer

## Request body

- GetUpdatesRequest
  - `beginExclusive` integer, required — Exclusive lower bound offset of the requested ledger section (non-negative integer). The response will only contain transactions whose offset is strictly greater than this. If set to zero, the lower bound is set to the beginning of the ledger. If the participant has been pruned, this parameter must be greater or equal than the pruning offset. Required
  - `endInclusive` integer — Inclusive higher bound offset of the requested ledger section. If specified the response will only contain transactions whose offset is less than or equal to this. If not specified, - the descending_order must not be selected, - the stream will not terminate. Optional
  - `filter` TransactionFilter — Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. Used both for filtering create and archive events as well as for filtering transaction trees.
    - `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
            - `Empty` Empty1, required
          - object
            - `InterfaceFilter` InterfaceFilter, required — This filter matches contracts that implement a specific interface.
              - …
          - object
            - `TemplateFilter` TemplateFilter, required — This filter matches contracts of a specific template.
              - …
          - object
            - `WildcardFilter` WildcardFilter, required — This filter matches all templates.
              - …
  - `verbose` boolean — Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. 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, record and variant type ids for record fields. Optional for backwards compatibility, if defined update_format must be unset
  - `updateFormat` UpdateFormat — 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 stream will populate the elements in descending order. Optional

## Response `200`

- JsGetUpdatesResponse[]
  - `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
            - `synchronizerId` string, required — The id of the synchronizer. Required
            - `recordTime` string, required — All commands with a maximum record time below this value MUST be considered lost if their completion has not arrived before this checkpoint. Required
    - 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
            - union
              - …
          - `traceContext` TraceContext
            - `traceparent` string — https://www.w3.org/TR/trace-context/ Optional
            - `tracestate` string — Optional
          - `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
            - `event` union
              - …
          - `traceContext` TraceContext
            - `traceparent` string — https://www.w3.org/TR/trace-context/ Optional
            - `tracestate` string — Optional
    - 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
            - union — Events in transactions can have two primary shapes: - ACS delta: events can be CreatedEvent or ArchivedEvent - ledger effects: events can be CreatedEvent or ExercisedEvent In the update service the events are restricted to the events visible for the parties specified in the transaction filter. Each event message type below contains a ``witness_parties`` field which indicates the subset of the requested parties that can see the event in question.
              - …
          - `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
            - `traceparent` string — https://www.w3.org/TR/trace-context/ Optional
            - `tracestate` string — Optional
          - `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

## Other responses

- `400` — Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_ms
- `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)