> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/spark-apis/execute-api/execute-api-v4.md).

# 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/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\_</code><em><code>", "valuation\_by\_</code></em><code>"]</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" %}
`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>