> ## 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 /v2/commands/command-completions

> Query completions list (blocking call) Subscribe to command completion events. This streaming endpoint provides more flexibility in filtering than the predecessor ``CompletionStream``. 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.

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

<div class="x2mdx-ref-hero">
  <p class="x2mdx-ref-summary">Query completions list (blocking call) Subscribe to command completion events. This streaming endpoint provides more flexibility in filtering than the predecessor `CompletionStream`. 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.</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--added" href="#history-added-3-5">Added 3.5</a>
  </div>
</div>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST \
    --url 'http://localhost:7575/v2/commands/command-completions' \
    --header 'Authorization: Bearer $TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
    "parties": [
      "<string>"
    ],
    "beginExclusive": 123
  }'
  ```

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

  url = "http://localhost:7575/v2/commands/command-completions"
  headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
  payload = json.loads(r'''{
    "parties": [
      "<string>"
    ],
    "beginExclusive": 123
  }''')
  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('http://localhost:7575/v2/commands/command-completions', {
    method: 'POST',
    headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
    body: JSON.stringify({
    "parties": [
      "<string>"
    ],
    "beginExclusive": 123
  }),
  });

  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 => 'http://localhost:7575/v2/commands/command-completions',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => <<<'JSON'
  {
    "parties": [
      "<string>"
    ],
    "beginExclusive": 123
  }
  JSON,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer <token>",
          "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", "http://localhost:7575/v2/commands/command-completions", bytes.NewBufferString(`{
    "parties": [
      "<string>"
    ],
    "beginExclusive": 123
  }`))
    req.Header.Set("Authorization", "Bearer <token>")
    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("http://localhost:7575/v2/commands/command-completions"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("""
  {
    "parties": [
      "<string>"
    ],
    "beginExclusive": 123
  }
  """))
      .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('http://localhost:7575/v2/commands/command-completions')
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer <token>'
  request['Content-Type'] = 'application/json'
  request.body = <<~JSON
  {
    "parties": [
      "<string>"
    ],
    "beginExclusive": 123
  }
  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"}}
  [
    {
      "completionResponse": {
        "Completion": {
          "value": {
            "commandId": "<string>",
            "status": {
              "code": 123,
              "message": "<string>",
              "details": [
                "<object>"
              ]
            },
            "updateId": "<string>",
            "userId": "<string>",
            "actAs": [
              "<string>"
            ],
            "submissionId": "<string>",
            "deduplicationPeriod": "<object>",
            "traceContext": {
              "traceparent": "<string>",
              "tracestate": "<string>"
            },
            "offset": 123,
            "synchronizerTime": {
              "synchronizerId": "<string>",
              "recordTime": "<string>"
            },
            "paidTrafficCost": 123
          }
        }
      }
    }
  ]
  ```

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

  ```json default theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "code": "<string>",
    "cause": "<string>",
    "correlationId": "<string>",
    "traceId": "<string>",
    "context": {},
    "resources": [
      [
        "<string>"
      ]
    ],
    "errorCategory": 123,
    "grpcCodeValue": 123,
    "retryInfo": "<string>",
    "definiteAnswer": false
  }
  ```
</ResponseExample>

## Authorizations

### httpAuth

<ParamField header="Authorization" type="string" required>
  HTTP bearer authentication. Send the token as `Authorization: Bearer &lt;token&gt;`. Ledger API standard JWT token
</ParamField>

### apiKeyAuth

<ParamField header="Sec-WebSocket-Protocol" type="string" required>
  API key authentication in the header. Ledger API standard JWT token (websocket)
</ParamField>

## Query parameters

<ParamField query="limit" type="number">
  OpenAPI type: <code>integer (int64)</code>.

  maximum number of elements to return, this param is ignored if is bigger than server setting
</ParamField>

<ParamField query="stream_idle_timeout_ms" type="number">
  OpenAPI type: <code>integer (int64)</code>.

  timeout to complete and send result if no new elements are received (for open ended streams)
</ParamField>

## Body

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

<ParamField body="parties" type="string[]">
  If specified, only completions of commands are included, which have at least one of the `act_as` parties in the given set of parties. Only Ledger API users with CanReadAsAnyParty permission allowed to provide no `parties`. Must be a valid PartyIdString (as described in `value.proto`). Optional: can be empty
</ParamField>

<ParamField body="beginExclusive" type="number">
  OpenAPI type: <code>integer (int64)</code>.

  This optional field indicates the minimum offset for completions. This can be used to resume an earlier completion stream. If not set the ledger uses the ledger begin offset instead. If specified, it must be a valid absolute offset (positive integer) or zero (ledger begin offset). If the ledger has been pruned, this parameter must be specified and greater than the pruning offset. (the pruning offset is accessible on the StateService.GetLatestPrunedOffsets endpoint) Optional
</ParamField>

## Responses

### 200

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

<ResponseField name="value" type="CompletionStreamResponse[]" required>
  <Expandable title="child attributes">
    <ResponseField name="completionResponse" type="CompletionResponse">
      Required

      <Expandable title="child attributes">
        <ResponseField name="Variant 1" type="object">
          <Expandable title="child attributes">
            <ResponseField name="Completion" type="Completion" required>
              A completion represents the status of a submitted command on the ledger: it can be successful or failed.

              <Expandable title="child attributes">
                <ResponseField name="value" type="Completion1" required>
                  A completion represents the status of a submitted command on the ledger: it can be successful or failed.

                  <Expandable title="child attributes">
                    <ResponseField name="commandId" type="string" required>
                      The ID of the succeeded or failed command. Must be a valid LedgerString (as described in `value.proto`). Required
                    </ResponseField>

                    <ResponseField name="status" type="JsStatus">
                      Identifies the exact type of the error. It uses the same format of conveying error details as it is used for the RPC responses of the APIs. Optional

                      <Expandable title="child attributes">
                        <ResponseField name="code" type="integer (int32)" required />

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

                        <ResponseField name="details" type="ProtoAny[]">
                          <Expandable title="child attributes">
                            <ResponseField name="typeUrl" type="string" required />

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

                            <ResponseField name="unknownFields" type="UnknownFieldSet" required>
                              <Expandable title="child attributes">
                                <ResponseField name="fields" type="Map_Int_Field" required />
                              </Expandable>
                            </ResponseField>

                            <ResponseField name="valueDecoded" type="string" />
                          </Expandable>
                        </ResponseField>
                      </Expandable>
                    </ResponseField>

                    <ResponseField name="updateId" type="string">
                      The update\_id of the transaction or reassignment that resulted from the command with command\_id. Only set for successfully executed commands. Must be a valid LedgerString (as described in `value.proto`). Optional
                    </ResponseField>

                    <ResponseField name="userId" type="string" required>
                      The user-id that was used for the submission, as described in `commands.proto`. Must be a valid UserIdString (as described in `value.proto`). Required
                    </ResponseField>

                    <ResponseField name="actAs" type="string[]" required>
                      The set of parties on whose behalf the commands were executed. Contains the `act_as` parties from `commands.proto` filtered to the requesting parties in CompletionStreamRequest. The order of the parties need not be the same as in the submission. Each element must be a valid PartyIdString (as described in `value.proto`). Required: must be non-empty
                    </ResponseField>

                    <ResponseField name="submissionId" type="string">
                      The submission ID this completion refers to, as described in `commands.proto`. Must be a valid LedgerString (as described in `value.proto`). Optional
                    </ResponseField>

                    <ResponseField name="deduplicationPeriod" type="DeduplicationPeriod1">
                      The actual deduplication window used for the submission, which is derived from `Commands.deduplication_period`. The ledger may convert the deduplication period into other descriptions and extend the period in implementation-specified ways. Used to audit the deduplication guarantee described in `commands.proto`. The deduplication guarantee applies even if the completion omits this field. Optional

                      <Expandable title="child attributes">
                        <ResponseField name="Variant 1" type="object">
                          <Expandable title="child attributes">
                            <ResponseField name="DeduplicationDuration" type="DeduplicationDuration1" required>
                              <Expandable title="child attributes">
                                <ResponseField name="value" type="Duration" required>
                                  <Expandable title="child attributes">
                                    <ResponseField name="seconds" type="integer (int64)" required />

                                    <ResponseField name="nanos" type="integer (int32)" required />

                                    <ResponseField name="unknownFields" type="UnknownFieldSet">
                                      This field is automatically added as part of protobuf to json mapping

                                      <Expandable title="child attributes">
                                        <ResponseField name="fields" type="Map_Int_Field" required />
                                      </Expandable>
                                    </ResponseField>
                                  </Expandable>
                                </ResponseField>
                              </Expandable>
                            </ResponseField>
                          </Expandable>
                        </ResponseField>

                        <ResponseField name="Variant 2" type="object">
                          <Expandable title="child attributes">
                            <ResponseField name="DeduplicationOffset" type="DeduplicationOffset1" required>
                              <Expandable title="child attributes">
                                <ResponseField name="value" type="integer (int64)" required />
                              </Expandable>
                            </ResponseField>
                          </Expandable>
                        </ResponseField>

                        <ResponseField name="Variant 3" type="object">
                          <Expandable title="child attributes">
                            <ResponseField name="Empty" type="Empty3" required />
                          </Expandable>
                        </ResponseField>
                      </Expandable>
                    </ResponseField>

                    <ResponseField name="traceContext" type="TraceContext">
                      The Ledger API trace context The trace context transported in this message corresponds to the trace context supplied by the client application in a HTTP2 header of the original command submission. We typically use a header to transfer this type of information. Here we use message body, because it is used in gRPC streams which do not support per message headers. This field will be populated with the trace context contained in the original submission. If that was not provided, a unique ledger-api-server generated trace context will be used instead. Optional

                      <Expandable title="child attributes">
                        <ResponseField name="traceparent" type="string">
                          [https://www.w3.org/TR/trace-context/](https://www.w3.org/TR/trace-context/) Optional
                        </ResponseField>

                        <ResponseField name="tracestate" type="string">
                          Optional
                        </ResponseField>
                      </Expandable>
                    </ResponseField>

                    <ResponseField name="offset" type="integer (int64)" required>
                      May be used in a subsequent CompletionStreamRequest to resume the consumption of this stream at a later time. Must be a valid absolute offset (positive integer). Required
                    </ResponseField>

                    <ResponseField name="synchronizerTime" type="SynchronizerTime" required>
                      The synchronizer along with its record time. The synchronizer id provided, in case of - successful/failed transactions: identifies the synchronizer of the transaction - for successful/failed unassign commands: identifies the source synchronizer - for successful/failed assign commands: identifies the target synchronizer Required

                      <Expandable title="child attributes">
                        <ResponseField name="synchronizerId" type="string" required>
                          The id of the synchronizer. Required
                        </ResponseField>

                        <ResponseField name="recordTime" type="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
                        </ResponseField>
                      </Expandable>
                    </ResponseField>

                    <ResponseField name="paidTrafficCost" type="integer (int64)">
                      The traffic cost paid by this participant node for the confirmation request for the submitted command. Commands whose execution is rejected before their corresponding confirmation request is ordered by the synchronizer will report a paid traffic cost of zero. If a confirmation request is ordered for a command, but the request fails (e.g., due to contention with a concurrent contract archival), the traffic cost is paid and reported on the failed completion for the request. If you want to correlate the traffic cost of a successful completion with the transaction that resulted from the command, you can use the `offset` field to retrieve the transaction using `UpdateService.GetUpdateByOffset` on the same participant node; or alternatively use the `update_id` field to retrieve the transaction using `UpdateService.GetUpdateById` on any participant node that sees the transaction. Note: for completions processed before the participant started serving traffic cost on the Ledger API, this field will be set to zero. Additionally, the total cost incurred by the submitting node for the submission of the transaction may be greater than the reported cost, for example if retries were issued due to failed submissions to the synchronizer. The cost reported here is the one paid for ordering the confirmation request. Optional
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Variant 2" type="object">
          <Expandable title="child attributes">
            <ResponseField name="Empty" type="Empty4" required />
          </Expandable>
        </ResponseField>

        <ResponseField name="Variant 3" type="object">
          <Expandable title="child attributes">
            <ResponseField name="OffsetCheckpoint" type="OffsetCheckpoint" required>
              OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption.

              <Expandable title="child attributes">
                <ResponseField name="value" type="OffsetCheckpoint1" required>
                  OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption.

                  <Expandable title="child attributes">
                    <ResponseField name="offset" type="integer (int64)" 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
                    </ResponseField>

                    <ResponseField name="synchronizerTimes" type="SynchronizerTime[]">
                      The times associated with each synchronizer at this offset. Optional: can be empty

                      <Expandable title="child attributes">
                        <ResponseField name="synchronizerId" type="string" required>
                          The id of the synchronizer. Required
                        </ResponseField>

                        <ResponseField name="recordTime" type="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
                        </ResponseField>
                      </Expandable>
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 400

Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream\_idle\_timeout\_ms

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">text/plain</span>
</div>

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

### default

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

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

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

<ResponseField name="correlationId" type="string" />

<ResponseField name="traceId" type="string" />

<ResponseField name="context" type="Map_String" required />

<ResponseField name="resources" type="Tuple2_String_String[]" />

<ResponseField name="errorCategory" type="integer (int32)" required />

<ResponseField name="grpcCodeValue" type="integer (int32)" />

<ResponseField name="retryInfo" type="string" />

<ResponseField name="definiteAnswer" type="boolean" />

## History

<div class="x2mdx-ref-history" aria-label="Reference history">
  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--introduced" id="history-added-3-5">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Added</span>
      <code class="x2mdx-ref-history-event-version">3.5</code>
    </div>
  </div>
</div>
