> ## Documentation Index > Fetch the complete documentation index at: https://cantonfoundation-update-ref-tables.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # POST /v0/events > Returns the event history in ascending order, paged, from ledger begin or optionally starting after a record time. An event bears some combination of a transaction, a contract reassignment, and a verdict. Events are ordered lexicographically by `(migration id, record time)`. For a given migration id, each event has a unique record time. The record time ranges of different migrations may overlap, i.e., it is not guaranteed that the maximum record time of one migration is smaller than the minimum record time of the next migration, and there may be two updates with the same record time but different migration ids. ## OpenAPI ````yaml /openapi/splice/scan/scan.yaml post /v0/events openapi: 3.0.0 info: title: Scan API version: 0.0.1 servers: - url: https://scan.sv-1.global.canton.network.sync.global/api/scan security: [] tags: - name: external description: > These endpoints are intended for public usage and will remain backward-compatible. - name: internal description: > For internal usage only, not guaranteed to be stable or backward-compatible. - name: deprecated description: | These endpoints are deprecated and will be removed in a future release. - name: scan description: | The internal and external endpoints. - name: pre-alpha description: | Still under active development, highly unstable. Do not use in production. paths: /v0/events: post: tags: - external - scan summary: POST /v0/events description: > Returns the event history in ascending order, paged, from ledger begin or optionally starting after a record time. An event bears some combination of a transaction, a contract reassignment, and a verdict. Events are ordered lexicographically by `(migration id, record time)`. For a given migration id, each event has a unique record time. The record time ranges of different migrations may overlap, i.e., it is not guaranteed that the maximum record time of one migration is smaller than the minimum record time of the next migration, and there may be two updates with the same record time but different migration ids. operationId: getEventHistory requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventHistoryRequest' responses: '200': description: ok content: application/json: schema: $ref: '#/components/schemas/EventHistoryResponse' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' components: schemas: EventHistoryRequest: type: object required: - page_size properties: after: $ref: '#/components/schemas/UpdateHistoryRequestAfter' description: > The events returned will either have a higher migration id or the same migration id and a record_time greater than the migration id and record time specified. page_size: description: | The maximum number of events returned for this request. type: integer format: int32 minimum: 1 maximum: 1000 daml_value_encoding: $ref: '#/components/schemas/DamlValueEncoding' EventHistoryResponse: type: object required: - events properties: events: type: array items: $ref: '#/components/schemas/EventHistoryItem' UpdateHistoryRequestAfter: type: object required: - after_migration_id - after_record_time properties: after_migration_id: type: integer format: int64 description: > The migration id from which to start returning transactions. This is inclusive. after_record_time: type: string description: > The record time to start returning transactions from. This only affects transactions with the same migration id as after_migration_id. Higher migration ids are always considered to be later. DamlValueEncoding: type: string description: > How daml values should be encoded in the response. "compact_json" is a compact, human-readable JSON encoding. It is the same encoding as the one used in the HTTP JSON API or the JavaScript codegen. "protobuf_json" is a verbose JSON encoding that is more difficult to parse, but contains type information, i.e., the values can be parsed losslessly without having access to the Daml source code. Optional and defaults to "compact_json". enum: - compact_json - protobuf_json EventHistoryItem: type: object description: > An event history item may contain a transaction update, a verdict from a mediator, both, or a contract reassignment. If an event pertains to a contract reassignment, there will be no verdict data. If an event pertains to a wholly private transaction, there will only be verdict data. If an event pertains to a transaction that is partially private, it may also bear verdict information for the private portions. When both fields are present, the transaction and verdict have the same `update_id` and `record_time`. For networks where the SVs enable activity record computation, a traffic summary and app activity record are present when a verdict is present. properties: update: $ref: '#/components/schemas/UpdateHistoryItemV2' nullable: true verdict: $ref: '#/components/schemas/EventHistoryVerdict' nullable: true traffic_summary: $ref: '#/components/schemas/EventHistoryTrafficSummary' nullable: true app_activity_records: $ref: '#/components/schemas/EventHistoryAppActivityRecords' nullable: true ErrorResponse: type: object required: - error properties: error: type: string UpdateHistoryItemV2: type: object description: > An individual item in the update history. May be a transaction or a contract reassignment. oneOf: - $ref: '#/components/schemas/UpdateHistoryTransactionV2' - $ref: '#/components/schemas/UpdateHistoryReassignment' EventHistoryVerdict: type: object required: - update_id - migration_id - domain_id - record_time - finalization_time - submitting_parties - submitting_participant_uid - verdict_result - mediator_group - transaction_views properties: update_id: description: | The ID of the transaction update associated with this verdict. type: string migration_id: description: > The migration id of the domain through which this event was sequenced. type: integer format: int64 domain_id: description: | The id of the domain through which this event was sequenced. type: string record_time: description: | The record_time of the transaction the verdict corresponds to. type: string finalization_time: description: > The finalization_time of the transaction the verdict corresponds to. Note that this time might be different between different scans/mediators. type: string submitting_parties: description: | Parties on whose behalf the transaction was submitted. type: array items: type: string submitting_participant_uid: description: | UID of the submitting participant. type: string verdict_result: $ref: '#/components/schemas/VerdictResult' description: | Result of the verdict. mediator_group: description: | The mediator group which finalized this verdict. type: integer format: int32 transaction_views: $ref: '#/components/schemas/TransactionViews' EventHistoryTrafficSummary: type: object description: > Traffic summary data from the sequencer for the confirmation request corresponding to an event. required: - total_traffic_cost - envelope_traffic_summaries properties: total_traffic_cost: description: > Total traffic cost of the confirmation request paid by the validator node that submitted it. type: integer format: int64 envelope_traffic_summaries: description: > Summary of traffic-related data for all envelopes in the confirmation request. type: array items: $ref: '#/components/schemas/EnvelopeTrafficSummary' EventHistoryAppActivityRecords: type: object description: > App activity record computed from verdicts and traffic summaries as per [CIP-104](https://github.com/canton-foundation/cips/blob/main/cip-0104/cip-0104.md). required: - round_number - records properties: round_number: description: | The round number assigned to the activity records. type: integer format: int64 records: description: | App activity records, one per app provider. type: array items: $ref: '#/components/schemas/AppActivityRecord' UpdateHistoryTransactionV2: allOf: - $ref: '#/components/schemas/BaseUpdateHistoryTransaction' - type: object properties: external_transaction_hash: description: > For an externally signed transaction, contains the external transaction hash signed by the external party. Can be used to correlate an external submission with a committed transaction. This field is conditionally omitted from JSON when null (see OmitNullString). type: string x-scala-type: org.lfdecentralizedtrust.splice.http.OmitNullString UpdateHistoryReassignment: type: object description: >- A contract reassignment between synchronizer. May be an assignment or unassignment. required: - update_id - offset - record_time - event properties: update_id: description: | The id of the update. type: string offset: description: > The absolute offset. Note that this field may not be the same across nodes, and therefore should not be compared between SVs. type: string record_time: description: | The time at which the transaction was sequenced. type: string event: description: | The reassignment event. May be an assignment or unassignment. type: object oneOf: - $ref: '#/components/schemas/UpdateHistoryAssignment' - $ref: '#/components/schemas/UpdateHistoryUnassignment' VerdictResult: type: string enum: - VERDICT_RESULT_UNSPECIFIED - VERDICT_RESULT_ACCEPTED - VERDICT_RESULT_REJECTED TransactionViews: type: object required: - views - root_views properties: views: type: array items: $ref: '#/components/schemas/TransactionView' root_views: type: array items: type: integer format: int32 EnvelopeTrafficSummary: type: object description: | Traffic cost for a single envelope and the view IDs contained in it required: - traffic_cost - view_ids properties: traffic_cost: description: | Traffic cost in bytes for this envelope. type: integer format: int64 view_ids: description: | View IDs from the verdict contained in this envelope type: array items: type: integer format: int32 AppActivityRecord: type: object description: | ActivityRecord for an app. required: - party - weight properties: party: description: | The app provider party identifier. type: string weight: description: | Activity weight in bytes of traffic. type: integer format: int64 BaseUpdateHistoryTransaction: type: object required: - update_id - migration_id - workflow_id - record_time - synchronizer_id - effective_at - root_event_ids - events_by_id properties: update_id: description: | The id of the update. type: string migration_id: description: | The migration id of the synchronizer. type: integer format: int64 workflow_id: description: | This transaction's Daml workflow ID; a workflow ID can be associated with multiple transactions. If empty, no workflow ID was set. type: string record_time: description: | The time at which the transaction was sequenced, with microsecond resolution, using ISO-8601 representation. type: string synchronizer_id: description: > The id of the synchronizer through which this transaction was sequenced. type: string effective_at: description: > Ledger effective time, using ISO-8601 representation. This is the time returned by `getTime` for all Daml executed as part of this transaction, both by the submitting participant and all confirming participants. type: string root_event_ids: description: | Roots of the transaction tree. These are guaranteed to occur as keys of the `events_by_id` object. type: array items: type: string events_by_id: x-scala-map-type: scala.collection.immutable.SortedMap description: > Changes to the ledger that were caused by this transaction, keyed by ID and sorted lexicographically by ID for display consistency. Values are nodes of the transaction tree. Within a transaction, IDs may be referenced by `root_event_ids` or `child_event_ids` in `ExercisedEvent` herein, which are sorted in the order as they occurred in the transaction. type: object additionalProperties: $ref: '#/components/schemas/TreeEvent' UpdateHistoryAssignment: type: object required: - submitter - source_synchronizer - target_synchronizer - migration_id - unassign_id - created_event - reassignment_counter properties: submitter: description: | The party ID who submitted this reassignment type: string source_synchronizer: description: | The id of the synchronizer from which the contract was reassigned type: string target_synchronizer: description: | The id of the synchronizer to which the contract was reassigned type: string migration_id: description: | The migration id of the target synchronizer type: integer format: int64 unassign_id: description: | The id of the corresponding unassign event; this assignment will usually, but not always, occur after the so-identified unassignment event. type: string created_event: $ref: '#/components/schemas/CreatedEvent' description: | The corresponding contract create event reassignment_counter: description: >- Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter 0. type: integer format: int64 UpdateHistoryUnassignment: type: object required: - submitter - source_synchronizer - migration_id - target_synchronizer - unassign_id - reassignment_counter - contract_id properties: submitter: description: | The party who submitted this reassignment type: string source_synchronizer: description: | The id of the synchronizer from which the contract was reassigned type: string migration_id: description: > The migration id of the synchronizer from which the contract was reassigned type: integer format: int64 target_synchronizer: description: | The id of the synchronizer to which the contract was reassigned type: string unassign_id: description: > The id of the unassign event, to later be correlated to an assign event type: string reassignment_counter: description: >- Each corresponding assigned and unassigned event has the same reassignment_counter. This strictly increases with each unassign command for the same contract. Creation of the contract corresponds to reassignment_counter 0. type: integer format: int64 contract_id: description: | The id of the unassigned contract type: string TransactionView: type: object required: - view_id - informees - confirming_parties - sub_views - view_hash properties: view_id: type: integer format: int32 informees: type: array items: type: string confirming_parties: type: array items: $ref: '#/components/schemas/Quorum' sub_views: type: array items: type: integer format: int32 view_hash: description: >- Hash of the view, for correlation with sequencer traffic data. Empty for older data ingested before this field was added. type: string TreeEvent: type: object description: | Either a creation or an exercise of a contract. oneOf: - $ref: '#/components/schemas/CreatedEvent' - $ref: '#/components/schemas/ExercisedEvent' discriminator: propertyName: event_type mapping: created_event: $ref: '#/components/schemas/CreatedEvent' exercised_event: $ref: '#/components/schemas/ExercisedEvent' CreatedEvent: type: object required: - event_type - event_id - contract_id - template_id - package_name - create_arguments - created_at - signatories - observers properties: event_type: type: string event_id: description: | The ID of this particular event. Equal to the key of this element of the containing `events_by_id` if this is part of a `TreeEvent`. type: string contract_id: description: | The ID of the created contract. type: string template_id: description: | The template of the created contract. type: string package_name: description: | The package name of the created contract. type: string create_arguments: description: | The arguments that have been used to create the contract, in the form of JSON representation of a Daml record. type: object created_at: description: | Ledger effective time of the transaction that created the contract. type: string format: date-time signatories: description: | Signatories to the contract, in the form of party IDs. type: array items: type: string observers: description: | Observers to the contract, in the form of party IDs. type: array items: type: string Quorum: type: object required: - parties - threshold properties: parties: type: array items: type: string threshold: type: integer format: int32 ExercisedEvent: type: object required: - event_type - event_id - contract_id - template_id - package_name - choice - choice_argument - child_event_ids - exercise_result - consuming - acting_parties properties: event_type: type: string event_id: description: | The ID of this particular event. Equal to the key of this element of the containing `events_by_id` if this is part of a `TreeEvent`. type: string contract_id: description: | The ID of the created contract. type: string template_id: description: | The template of the created contract. type: string package_name: description: | The package name of the created contract. type: string choice: description: > The choice that was exercised on the target contract, as an unqualified choice name, i.e. with no package or module name qualifiers. type: string choice_argument: description: > The argument of the exercised choice, in the form of JSON representation of a Daml value. This is usually a record with field names being the argument names, even in the case of a single apparent choice argument, which is represented as a single-element Daml record. type: object child_event_ids: description: > References to further events in the same transaction that appeared as a result of this ExercisedEvent. It contains only the immediate children of this event, not all members of the subtree rooted at this node. The order of the children is the same as the event order in the transaction. type: array items: type: string exercise_result: description: | The result of exercising the choice, as the JSON representation of a Daml value. type: object consuming: description: | If true, the target contract may no longer be exercised. type: boolean acting_parties: description: | The parties that exercised the choice, in the form of party IDs. type: array items: type: string interface_id: description: | The interface where the choice is defined, if inherited. type: string responses: '400': description: bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ````