> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-reference-full-stack-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/updates

> Returns the update history in ascending order, paged, from ledger begin or optionally starting after a record time. Unlike /v0/updates, this endpoint returns responses that are consistent across different scan instances. Event ids returned by this endpoint are not comparable to event ids returned by /v0/updates. Updates are ordered lexicographically by `(migration id, record time)`. For a given migration id, each update has a unique record time.

<div class="x2mdx-ref-page x2mdx-ref-page--operation x2mdx-ref-page--manual-api" />

<div class="x2mdx-ref-hero">
  <p class="x2mdx-ref-summary">Returns the update history in ascending order, paged, from ledger begin or optionally starting after a record time. Unlike /v0/updates, this endpoint returns responses that are consistent across different scan instances. Event ids returned by this endpoint are not comparable to event ids returned by /v0/updates. Updates are ordered lexicographically by `(migration id, record time)`. For a given migration id, each update has a unique record time.</p>

  <div class="x2mdx-ref-badges">
    <span class="x2mdx-ref-badge x2mdx-ref-badge--protocol">OpenAPI</span>

    <a class="x2mdx-ref-badge x2mdx-ref-badge--changed" href="#history-updated-0-6-0">Updated 0.6.0</a>

    <a class="x2mdx-ref-badge x2mdx-ref-badge--removed" href="#history-deprecated-0-5-10">Deprecated 0.5.10</a>
  </div>
</div>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url 'https://scan.sv-1.global.canton.network.sync.global/api/scan/v1/updates' \
    --header 'Content-Type: application/json' \
    --data '{
    "after": {
      "after_migration_id": 123,
      "after_record_time": "<string>"
    },
    "page_size": 123,
    "daml_value_encoding": "compact_json"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import json
  import requests

  url = "https://scan.sv-1.global.canton.network.sync.global/api/scan/v1/updates"
  headers = {'Content-Type': 'application/json'}
  payload = json.loads(r'''{
    "after": {
      "after_migration_id": 123,
      "after_record_time": "<string>"
    },
    "page_size": 123,
    "daml_value_encoding": "compact_json"
  }''')
  response = requests.request(
      "POST", url, headers=headers, json=payload
  )

  print(response.text)
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://scan.sv-1.global.canton.network.sync.global/api/scan/v1/updates', {
    method: 'POST',
    headers: {
    "Content-Type": "application/json"
  },
    body: JSON.stringify({
    "after": {
      "after_migration_id": 123,
      "after_record_time": "<string>"
    },
    "page_size": 123,
    "daml_value_encoding": "compact_json"
  }),
  });

  console.log(await response.text());
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://scan.sv-1.global.canton.network.sync.global/api/scan/v1/updates',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => <<<'JSON'
  {
    "after": {
      "after_migration_id": 123,
      "after_record_time": "<string>"
    },
    "page_size": 123,
    "daml_value_encoding": "compact_json"
  }
  JSON,
      CURLOPT_HTTPHEADER => [
          "Content-Type: application/json"
      ],
  ]);

  $response = curl_exec($curl);
  echo $response;
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  package main

  import (
    "bytes"
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    req, _ := http.NewRequest("POST", "https://scan.sv-1.global.canton.network.sync.global/api/scan/v1/updates", bytes.NewBufferString(`{
    "after": {
      "after_migration_id": 123,
      "after_record_time": "<string>"
    },
    "page_size": 123,
    "daml_value_encoding": "compact_json"
  }`))
    req.Header.Set("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(req)
    defer response.Body.Close()
    body, _ := io.ReadAll(response.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  var request = HttpRequest.newBuilder()
      .uri(URI.create("https://scan.sv-1.global.canton.network.sync.global/api/scan/v1/updates"))
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("""
  {
    "after": {
      "after_migration_id": 123,
      "after_record_time": "<string>"
    },
    "page_size": 123,
    "daml_value_encoding": "compact_json"
  }
  """))
      .build();
  var response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={"theme":{"light":"github-light","dark":"github-dark"}}
  require 'net/http'
  require 'uri'

  uri = URI('https://scan.sv-1.global.canton.network.sync.global/api/scan/v1/updates')
  request = Net::HTTP::Post.new(uri)
  request['Content-Type'] = 'application/json'
  request.body = <<~JSON
  {
    "after": {
      "after_migration_id": 123,
      "after_record_time": "<string>"
    },
    "page_size": 123,
    "daml_value_encoding": "compact_json"
  }
  JSON
  response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(request)
  end
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "transactions": [
      {
        "update_id": "<string>",
        "migration_id": 123,
        "workflow_id": "<string>",
        "record_time": "<string>",
        "synchronizer_id": "<string>",
        "effective_at": "<string>",
        "offset": "<string>",
        "root_event_ids": [
          "<string>"
        ],
        "events_by_id": {},
        "external_transaction_hash": "<string>"
      }
    ]
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": "<string>"
  }
  ```

  ```json 500 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "error": "<string>"
  }
  ```
</ResponseExample>

## Body

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ParamField body="after" type="object">
  OpenAPI type: <code>UpdateHistoryRequestAfter</code>.

  The transactions 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.

  <Expandable title="child attributes">
    <ParamField body="after_migration_id" type="number" required>
      OpenAPI type: <code>integer (int64)</code>.

      The migration id from which to start returning transactions. This is inclusive.
    </ParamField>

    <ParamField body="after_record_time" type="string" required>
      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.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="page_size" type="number" required>
  OpenAPI type: <code>integer (int32)</code>.

  The maximum number of transactions returned for this request.
</ParamField>

<ParamField body="daml_value_encoding" type="object">
  OpenAPI type: <code>DamlValueEncoding</code>.

  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".

  Allowed values: <code>compact\_json</code>, <code>protobuf\_json</code>.
</ParamField>

## Responses

### 200

ok

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="transactions" type="UpdateHistoryItem[]" required>
  <Expandable title="child attributes">
    <ResponseField name="UpdateHistoryTransaction" type="UpdateHistoryTransaction">
      <Expandable title="child attributes">
        <ResponseField name="update_id" type="string" required>
          The id of the update.
        </ResponseField>

        <ResponseField name="migration_id" type="integer (int64)" required>
          The migration id of the synchronizer.
        </ResponseField>

        <ResponseField name="workflow_id" type="string" required>
          This transaction's Daml workflow ID; a workflow ID can be associated with multiple transactions. If empty, no workflow ID was set.
        </ResponseField>

        <ResponseField name="record_time" type="string" required>
          The time at which the transaction was sequenced, with microsecond resolution, using ISO-8601 representation.
        </ResponseField>

        <ResponseField name="synchronizer_id" type="string" required>
          The id of the synchronizer through which this transaction was sequenced.
        </ResponseField>

        <ResponseField name="effective_at" type="string" required>
          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.
        </ResponseField>

        <ResponseField name="offset" type="string" required>
          The absolute offset. Note that this field may not be the same across nodes, and therefore should not be compared between SVs. However, within a single SV's scan, it is monotonically, lexicographically increasing.
        </ResponseField>

        <ResponseField name="root_event_ids" type="string[]" required>
          Roots of the transaction tree. These are guaranteed to occur as keys of the `events_by_id` object.
        </ResponseField>

        <ResponseField name="events_by_id" type="object" required>
          Changes to the ledger that were caused by this transaction, keyed by ID. 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.
        </ResponseField>

        <ResponseField name="external_transaction_hash" type="string">
          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).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="UpdateHistoryReassignment" type="UpdateHistoryReassignment">
      A contract reassignment between synchronizer. May be an assignment or unassignment.

      <Expandable title="child attributes">
        <ResponseField name="update_id" type="string" required>
          The id of the update.
        </ResponseField>

        <ResponseField name="offset" type="string" required>
          The absolute offset. Note that this field may not be the same across nodes, and therefore should not be compared between SVs.
        </ResponseField>

        <ResponseField name="record_time" type="string" required>
          The time at which the transaction was sequenced.
        </ResponseField>

        <ResponseField name="event" type="oneOf" required>
          The reassignment event. May be an assignment or unassignment.

          <Expandable title="child attributes">
            <ResponseField name="UpdateHistoryAssignment" type="UpdateHistoryAssignment">
              <Expandable title="child attributes">
                <ResponseField name="submitter" type="string" required>
                  The party ID who submitted this reassignment
                </ResponseField>

                <ResponseField name="source_synchronizer" type="string" required>
                  The id of the synchronizer from which the contract was reassigned
                </ResponseField>

                <ResponseField name="target_synchronizer" type="string" required>
                  The id of the synchronizer to which the contract was reassigned
                </ResponseField>

                <ResponseField name="migration_id" type="integer (int64)" required>
                  The migration id of the target synchronizer
                </ResponseField>

                <ResponseField name="unassign_id" type="string" required>
                  The id of the corresponding unassign event; this assignment will usually, but not always, occur after the so-identified unassignment event.
                </ResponseField>

                <ResponseField name="created_event" type="CreatedEvent" required>
                  The corresponding contract create event

                  <Expandable title="child attributes">
                    <ResponseField name="event_type" type="string" required />

                    <ResponseField name="event_id" type="string" required>
                      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`.
                    </ResponseField>

                    <ResponseField name="contract_id" type="string" required>
                      The ID of the created contract.
                    </ResponseField>

                    <ResponseField name="template_id" type="string" required>
                      The template of the created contract.
                    </ResponseField>

                    <ResponseField name="package_name" type="string" required>
                      The package name of the created contract.
                    </ResponseField>

                    <ResponseField name="create_arguments" type="object" required>
                      The arguments that have been used to create the contract, in the form of JSON representation of a Daml record.
                    </ResponseField>

                    <ResponseField name="created_at" type="string (date-time)" required>
                      Ledger effective time of the transaction that created the contract.
                    </ResponseField>

                    <ResponseField name="signatories" type="string[]" required>
                      Signatories to the contract, in the form of party IDs.
                    </ResponseField>

                    <ResponseField name="observers" type="string[]" required>
                      Observers to the contract, in the form of party IDs.
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="reassignment_counter" type="integer (int64)" required>
                  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.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="UpdateHistoryUnassignment" type="UpdateHistoryUnassignment">
              <Expandable title="child attributes">
                <ResponseField name="submitter" type="string" required>
                  The party who submitted this reassignment
                </ResponseField>

                <ResponseField name="source_synchronizer" type="string" required>
                  The id of the synchronizer from which the contract was reassigned
                </ResponseField>

                <ResponseField name="migration_id" type="integer (int64)" required>
                  The migration id of the synchronizer from which the contract was reassigned
                </ResponseField>

                <ResponseField name="target_synchronizer" type="string" required>
                  The id of the synchronizer to which the contract was reassigned
                </ResponseField>

                <ResponseField name="unassign_id" type="string" required>
                  The id of the unassign event, to later be correlated to an assign event
                </ResponseField>

                <ResponseField name="reassignment_counter" type="integer (int64)" required>
                  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.
                </ResponseField>

                <ResponseField name="contract_id" type="string" required>
                  The id of the unassigned contract
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 400

bad request

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

### 500

internal server error

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

## History

<div class="x2mdx-ref-history" aria-label="Reference history">
  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--changed" id="history-updated-0-6-0">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Updated</span>
      <code class="x2mdx-ref-history-event-version">0.6.0</code>
    </div>

    <p class="x2mdx-ref-history-event-detail">The POST /v1/updates operation changed in this snapshot.</p>
  </div>

  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--changed" id="history-updated-0-5-17">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Updated</span>
      <code class="x2mdx-ref-history-event-version">0.5.17</code>
    </div>

    <p class="x2mdx-ref-history-event-detail">The POST /v1/updates operation changed in this snapshot.</p>
  </div>

  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--deprecated" id="history-deprecated-0-5-10">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Deprecated</span>
      <code class="x2mdx-ref-history-event-version">0.5.10</code>
    </div>
  </div>
</div>