---
title: "POST /v2/updates/update-by-id"
method: POST
path: "/v2/updates/update-by-id"
---

# POST /v2/updates/update-by-id

`POST /v2/updates/update-by-id`

Lookup an update by its ID.
If there is no update with this ID, or all the events are filtered, an UPDATE_NOT_FOUND error will be raised.

## Request body

- GetUpdateByIdRequest
  - `updateId` string, required — The ID of a particular update. Must be a valid LedgerString (as described in ``value.proto``). Required
  - `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

## Response `200`

- JsGetUpdateResponse
  - `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
- `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)