---
title: "POST /v2/updates/trees"
method: POST
path: "/v2/updates/trees"
deprecated: true
---

# POST /v2/updates/trees

`POST /v2/updates/trees`

> **Deprecated.**

Query update transactions tree list (blocking call). Provided for backwards compatibility, it will be removed in the Canton version 3.5.0, use v2/updates instead.
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`

- JsGetUpdateTreesResponse[]
  - `update` union
    - object
      - `OffsetCheckpoint` OffsetCheckpoint3, 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` Reassignment1, 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
      - `TransactionTree` TransactionTree, required — Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. Complete view of an on-ledger transaction.
        - `value` JsTransactionTree, required — Provided for backwards compatibility, it will be removed in the Canton version 3.5.0. Complete view of an on-ledger transaction.
          - `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. Only set if the ``workflow_id`` for the command was set. Must be a valid LedgerString (as described in ``value.proto``). Optional
          - `effectiveAt` string, required — Ledger effective time. Required
          - `offset` integer, required — The absolute offset. The details of this field are described in ``community/ledger-api/README.md``. Required, it is a valid absolute offset (positive integer).
          - `eventsById` MapIntTreeEvent, 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

## 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)