# Execute API (v4)

Execute multiple calculations from a Spark service.

Returns: Service execution response.

Each Spark service can be called to perform calculations by calling the [Execute API](/spark-apis/execute-api.md). The `v4` specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time. This API specification also forms the basis for using the [Batch APIs](/spark-apis/batch-apis.md) and [Introduction to XConnector](/xconnector/introduction-to-xconnector.md).

{% hint style="danger" %}
This endpoint should not be used for very large number of input records because there is an execution time limit of `55 s`  and an error will be returned.

For very large numbers of input records, we recommend using applications that utilize the [Batch APIs](/spark-apis/batch-apis.md).
{% endhint %}

{% code overflow="wrap" %}

```shellscript
POST /{tenant}/api/v4/execute
POST /{tenant}/api/v4/public/execute
```

{% endcode %}

### Authorization

* `Bearer {token}` accessible from [Authorization - Bearer token](/spark-apis/authorization-bearer-token.md) or systematically via [Client Credentials](/identity-and-access-management/client-credentials.md).
  * The request headers should include a key for `Authorization` with the value `Bearer {token}`.
* API key created from [Authorization - API keys](/spark-apis/authorization-api-keys.md).\
  The [Authorization - API keys](/spark-apis/authorization-api-keys.md#api-key-groups) must contain [Manage users](/tenant-administration/manage-users.md#user-groups) that are also assigned to [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions.md) `Spark.SyncBatch.json` or `Spark.AllEncompassingProxy.json`.
  * The request headers should include the keys `x-synthetic-key` and `x-tenant-name` with the values of the API key and tenant name respectively.
* No Authorization is required for [Authorization - Public APIs](/spark-apis/authorization-public-apis.md).

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the  <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr></tbody></table>

### Request body

`Content-Type: application/json`

| Name                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputs`               | See [#inputs-definitions](#inputs-definitions "mention")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `service`              | <p>URI or <code>service\_id</code> of the service being called.<br>Example 1: <code>stocks/NVDA</code></p><p>Example 2: <code>stocks/NVDA\[1.4.3]</code></p><p>Example 3:  <code>stocks/NVDA\[1.4]</code> take the latest version starting with <code>1.4.</code></p><p>Example 4: <code>stocks/NVDA\[1]</code> take the latest version starting with <code>1.</code></p><p>Example 5: <code>/folders/stocks/services/NVDA</code><br>Example 6: <code>a5e3f03a-57ca-4889-adae-0630be54bd87</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `version_id`           | <p><code>version\_id</code> of the requested service version.<br>Example: <code>8183f03a-57ca-4889-adae-0630be54bd87</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `version_by_timestamp` | <p>Timestamp to resolve the service version for <a data-mention href="/pages/-Mbp9Z03Ck-4xgQWd-9o">/pages/-Mbp9Z03Ck-4xgQWd-9o</a>.</p><p>Use <a href="https://www.timestamp-converter.com/">Timestamp Converter</a> to convert dates to ISO 8601.</p><ul><li><p>When call to a service is made using a URI   or <code>service\_id</code> this is used to determine the latest version of a service which have effective start and effective end dates that bound <code>version\_by\_timestamp</code>.</p><ul><li>If omitted, the current date and time is used.</li><li>If the <code>version\_by\_timestamp</code> does not fall within the effective start and effective end dates of any versions, then the response will be an error.</li></ul></li><li>When calling a specific version using <code>version</code> or <code>version\_id</code> this field has no effect. </li></ul><p>Example: <code>2023-10-31T01:30:00.000-05:00</code></p> |
| `output`               | <p>Array of strings to denote the <code>output</code>s to keep in the results. The strings can also contain regular expressions.<br>Example 1: <code>\["value\_*", "valuation\_by\_*"]</code></p><p><br>Alternatively direct references to Excel ranges are possible.</p><p>For <code>Neuron</code> <code>1.17.0</code> and later this can be enabled In Excel by adding a Named Range referenced to a cell called <code>xBuildParams</code>. The cell contents must contain <code>'--direct\_addressing=true</code>.</p><p>Example 2: <code>\["@Sheet1!B2:D4"]</code></p><p>Example 3: <code>\["@MyNamedRange"]</code></p><p>Furthermore if <code>#SparkFormulaValueVector</code> is added to these requests, only the calculated results would be returned.</p>                                                                                                                                                                                 |
| `compiler_type`        | <p>Calculation engine for the request. By default this uses the setting defined in <a href="https://docs.coherent.global/navigation/service-documentation#change-the-default-service-type">Change the Default Service Type</a>. Note that <code>Type3</code> is not supported with this version of the API specification.<br>Example: <code>Neuron</code> or <code>Xconnector</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `manual_now`           | <p><a data-mention href="/pages/qc2ynJ5gnthNAqVrFQRg">/pages/qc2ynJ5gnthNAqVrFQRg</a> behavior:<br>Default behavior in Spark for the Excel <a href="https://support.microsoft.com/en-us/office/now-function-3337fd29-145a-4347-b2e6-20c904739c46"><code>NOW()</code></a> and <a href="https://support.microsoft.com/en-us/office/today-function-5eb3078d-a82c-4736-8930-2f51a028fdd9"><code>TODAY()</code></a> functions are to return the value based upon server time. If a <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch time</a> is provided, then that will be used to derive the current time and date instead.<br>Example: <code>1650593119</code> would represent <code>2024-10-29T02:44:48</code></p>                                                                                                                                                                                                                     |
| `call_purpose`         | <p>Tag API Call. Can be queried in <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0\_</a>.</p><p>Example: <code>admin system p</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `correlation_id`       | <p>Tag API Call. Can be queried in <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0\_</a>.</p><p>Example: <code>456</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `source_system`        | <p>Tag API Call. Can be queried in <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0\_</a>.</p><p>Example: <code>mycicd</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `subservice`           | <p>Comma separated string of subservice names. Reference <a data-mention href="/pages/-MbpBc-9qZgA0SNngR3Q">/pages/-MbpBc-9qZgA0SNngR3Q</a>.<br></p><p>When this is not specified or set as  <code>#Default#</code>, outputs not related to subservices are shown.</p><p>Example 1: <code>subservice1</code> will only show the the outputs from <code>subservice1</code>.</p><p>Example 2: <code>subservice1,subservice2</code> will only show the outputs from <code>subservice1</code> and <code>subservice2</code>.</p><p>Example 3: <code>#Default#,subservice2</code> will show outputs not relating to subservices and from <code>subservice2</code>.</p><p>Example 4: <code>\*</code> all subservices will be included</p>                                                                                                                                                                                                                |

#### `inputs` definitions

Refer to [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#request_data) for information about input definitions and data types.

**Synchronous request of `inputs` using JSON objects**

If using JSON objects, a synchronous request containing multiple records can be made by stacking the request objects together within the `inputs` array. The requests are formatted in a similar way to the [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#request_data). The response will also be returned in a similar format, with `outputs` being an array of JSON objects corresponding to each record.

In this example, the service has 2 inputs: `A` is a single value and `B` is a `3x2` table comprising of the headers `B1` and `B2`. This request includes 2 records for calculation.

```json
{
    "inputs": [
        {
            "A": 1,
            "B": [
                {"B1": 6, "B2": 3},
                {"B1": 9, "B2": 4}
            ]
        },
        {
            "A": 7,
            "B": [
                {"B1": 0, "B2": 2}
            ]
        }
    ]
}
```

**Synchronous request of `inputs` using JSON arrays**

If using JSON arrays, a synchronous request containing multiple records can be defined in the following structure:

* The first row contains the name of the inputs in an array.
* The subsequent rows define the values for the corresponding records, in this case `A` and `B`. If an input is a table, its table headings are also included in the data, in this case `B1` and `B2` are repeated in each entry.
* This format is much more compact for large datasets and used for the [Batch APIs](/spark-apis/batch-apis.md) and [Introduction to XConnector](/xconnector/introduction-to-xconnector.md).
* The response will also be returned in a similar format.

In this example, the service has 2 inputs: `A` is a single value and `B` is a `3x2` table comprising of the headers `B1` and `B2`. This request includes 2 records for calculation.

```json
{
    "inputs": [
        ["A", "B"],
        [1, 
            [
                ["B1", "B2"],
                [6, 3],
                [9, 4]
            ]
        ],
        [7,
            [
                ["B1", "B2"],
                [0, 2]
            ]
        ]
    ]
}
```

**Parameters to resolve Spark service versions**

Spark will use the parameters `version_id`, `service`,  and `version_by_timestamp` in order to resolve down to the most appropriate `version_id` to use for an API call. Learn more about the version resolution in the section [Manage service versions and effective dates](/build-spark-services/manage-versions-and-effective-dates.md).

{% hint style="info" %}
&#x20;`version_id` will be resolved by Spark the quickest.
{% endhint %}

{% hint style="info" %}
Execute API will always resolve the `version_id` parameter first, `service_id` parameter second, and then `service` last. It is possible that these 3 may refer to different services entirely but Spark will resolve the reference in the same order.
{% endhint %}

### Sample request

The `2` sample requests will give equivalent results with different JSON formatting.

* `A11` is a single value.
* `A33` is an input table with headers `A1`, `A2`, `A3`.
* `A44` is an input table with headings `A1`, `B` (with subheadings `B1`, `B2`), and `C1`.

<table data-full-width="false"><thead><tr><th>Array of JSON objects</th><th>Array of JSON arrays</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">{
    "inputs": [
        {
            "A11":10,
            "A33":[
                {"A1":10,"A2":20,"A3":30},
                {"A1":110,"A2":120,"A3":130}
            ],
            "A44":[
                {"A1":10,"B.B1":20,"B.B2":30,"C1":40},
                {"A1":110,"B.B1":120,"B.B2":130,"C1":140}
            ]
        },
        {
            "A11":20,
            "A33":[
                {"A1":20,"A2":40,"A3":60},
                {"A1":220,"A2":240,"A3":260}
            ],
            "A44":[
                {"A1":20,"B.B1":40,"B.B2":60,"C1":80},
                {"A1":20,"B.B1":240,"B.B2":260,"C1":280}
            ]
        }
    ],
    "service": "MyFolder/BlockParty",
    "call_purpose": "Array of JSON objects"
}
</code></pre></td><td><pre class="language-json"><code class="lang-json">{
    "inputs": [
        ["A11","A33","A44"],
        [10,
            [
                ["A1","A2","A3"],
                [10,20,30],
                [110,120,130]
            ],
            [
                ["A1","B.B1","B.B2","C1"],
                [10,20,30,40],
                [110,120,130,140]
            ]
        ],
        [20,
            [
                ["A1","A2","A3"],
                [20,40,60],
                [220,240,260]
            ],
            [
                ["A1","B.B1","B.B2","C1"],
                [20,40,60,80],
                [220,240,260,280]
            ]
        ]
    ],
    "service": "MyFolder/BlockParty",
    "call_purpose": "Array of JSON arrays"
}
</code></pre></td></tr></tbody></table>

### Response body

`Content-Type: application/json`

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>outputs</code></td><td>Array of outputs. The elements of the array correspond to the input request records.<br>Outputs will be formatted in a similar way to the inputs. The layout of <code>outputs</code> depends on whether the <code>inputs</code> comprised of an array of JSON objects or JSON arrays. </td></tr><tr><td><code>process_time</code></td><td><p>Array representing the time for Spark to process each record of the API call. The elements of the array correspond to the input request records.</p><p>Example: <code>[39, 24]</code></p></td></tr><tr><td><code>errors</code></td><td>Array of errors. The elements of the array correspond to the input request records. Reference <a data-mention href="/pages/nsJig8FRhYDL3hcSAwbt#response_data">/pages/nsJig8FRhYDL3hcSAwbt#response_data</a>.</td></tr><tr><td><code>warnings</code></td><td>Array of warnings. The elements of the array correspond to the input request records. Reference <a data-mention href="/pages/nsJig8FRhYDL3hcSAwbt#response_data">/pages/nsJig8FRhYDL3hcSAwbt#response_data</a>.</td></tr><tr><td><code>service_id</code></td><td><p><code>service_id</code> of the resolved service.</p><p>Example: <code>48a953cc-ed34-4454-b5c7-1141912f2f8d</code></p></td></tr><tr><td><code>version_id</code></td><td><code>version_id</code> of the resolved service version.<br>Example: <code>6bf49dca-5bc2-4144-9710-5988a0f44163</code></td></tr><tr><td><code>version</code></td><td><p>Resolved service version number.</p><p>Example: <code>4.15.2</code></p></td></tr><tr><td><code>call_id</code></td><td><p>Universally unique identifier for this API Call. This can be referenced in the <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0_</a>.</p><p>Example: <code>f6123393-d33f-4ff6-86a4-a663111afd82</code></p></td></tr><tr><td><code>compiler_version</code></td><td><p>Compiler version of this service version.</p><p>Example: <code>4.15.2</code></p></td></tr><tr><td><code>correlation_id</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>request_timestamp</code></td><td><p>Request timestamp.</p><p>Example: <code>2020-10-29T09:53:18.8314052Z</code></p></td></tr></tbody></table>

### Sample response

`HTTP 200 OK` `Content-Type: application/json`

<table data-full-width="false"><thead><tr><th>Array of JSON objects</th><th>Array of JSON arrays</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">{
    "outputs": [
        {
            "A11":20,
            "A33":[                
                {"A1":20,"A2":40,"A3":60},
                {"A1":220,"A2":240,"A3":260}
            ],
            "A44":[
                {"A1":20,"B.B1":40,"B.B2":60,"C1":80},
                {"A1":220,"B.B1":240,"B.B2":260,"C1":280}
            ]
        },
        {
            "A11":40,
            "A33":[
                {"A1":40,"A2":80,"A3":120},
                {"A1":440,"A2":480,"A3":520}
            ],
            "A44":[
                {"A1":40,"B.B1":80,"B.B2":120,"C1":160},
                {"A1":440,"B.B1":480,"B.B2":520,"C1":560}
            ]
        }
    ],
    "process_time": [1,1],
    "warnings": [null,null],
    "errors": [
        [
            {
                "source_path": "$.Input.A11",
                "error_category": "validation_error",
                "error_type": "error.VALIDATION",
                "message": "Input Not Valid",
                "additional_details": "BlockParty"
            }
        ],
        [
            {
                "source_path": "$.Input.A11",
                "error_category": "validation_error",
                "error_type": "error.VALIDATION",
                "message": "Input Not Valid",
                "additional_details": "BlockParty"
            }
        ]
    ],
    "service_id": "daa1ed5f-6a41-43dd-99ff-20bceca73f81",
    "version_id": "f3849415-0d2d-44b8-afbd-aab27ce73b43",
    "version": "0.1.0",
    "call_id": "e0a71fd5-1589-4277-b74a-7ccdd39cd628",
    "compiler_version": "1.16.0",
    "correlation_id": null,
    "request_timestamp": "2024-03-12T02:52:45.531Z"
}
</code></pre></td><td><pre class="language-json"><code class="lang-json">{
    "outputs": [
        ["A11","A33","A44"],
        [20,
            [
                ["A1","A2","A3"],
                [20,40,60],
                [220,240,260]
            ],
            [
                ["A1","B.B1","B.B2","C1"],
                [20,40,60,80],
                [220,240,260,280]
            ]
        ],
        [40,
            [
                ["A1","A2","A3"],
                [40,80,120],
                [440,480,520]
            ],
            [
                ["A1","B.B1","B.B2","C1"],
                [40,80,120,160],
                [440,480,520,560]
            ]
        ]
    ],
    "process_time": [1,1],
    "warnings": [null,null],
    "errors": [
        [
            {
                "source_path": "$.Input.A11",
                "error_category": "validation_error",
                "error_type": "error.VALIDATION",
                "message": "Input Not Valid",
                "additional_details": "BlockParty"
            }
        ],
        [
            {
                "source_path": "$.Input.A11",
                "error_category": "validation_error",
                "error_type": "error.VALIDATION",
                "message": "Input Not Valid",
                "additional_details": "BlockParty"
            }
        ]
    ],
    "service_id": "daa1ed5f-6a41-43dd-99ff-20bceca73f81",
    "version_id": "f3849415-0d2d-44b8-afbd-aab27ce73b43",
    "version": "0.1.0",
    "call_id": "bb4cf8fb-358e-4fc8-9a0b-19dbdb219e81",
    "compiler_version": "1.16.0",
    "correlation_id": null,
    "request_timestamp": "2024-03-12T05:14:37.912Z"
}
</code></pre></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coherent.global/spark-apis/execute-api/execute-api-v4.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.