# Execute API (v4)

Execute multiple calculations from a Spark service. Supports synchronous batching enabling multiple requests to be submitted at the same time. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v4) for more details.\
\
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](https://docs.coherent.global/spark-apis/batch-apis).

## Generic execute endpoint

> The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time.\<br>\<br> If using an API key, the API key group must contain user groups that are also assigned to \`Spark.SyncBatch.json\` or \`Spark.AllEncompassingProxy.json\`.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v4)","description":"Execute multiple calculations from a Spark service. Supports synchronous batching enabling multiple requests to be submitted at the same time. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v4) for more details.<br><br> 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](https://docs.coherent.global/spark-apis/batch-apis)."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[],"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Tenant is part of your login URL and also available in the user menu.","schema":{"type":"string"}}},"requestBodies":{"executeV4":{"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":["null","array"],"items":{"oneOf":[{"type":"array","items":{},"description":"For JSON arrays format, the first row contains the name of the inputs in an array, and subsequent rows define the values for the corresponding records."},{"type":"object","description":"For JSON objects format, each element is an object containing key-value pairs that will be passed to the fields identified as Xinput in the workbook."}]},"description":"Array of input records."},"service":{"type":["null","string"],"description":"URI or `service_id` of the service being called."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"version_id of the requested service version. This will be resolved by Spark the quickest."},"version_by_timestamp":{"type":["null","string"],"anyOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"output":{"type":["null","array"],"items":{"type":["null","string"]},"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"subservice":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."}}}}}}},"responses":{"executeV4":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"properties":{"outputs":{"type":["null","array"],"items":{"oneOf":[{"type":"array","items":{},"description":"Array of JSON arrays."},{"type":"object","description":"Array of JSON objects."}]},"description":"Array of outputs. The elements of the array correspond to the input request records. Outputs will be formatted in a similar way to the inputs. The layout of outputs depends on whether the inputs comprised of an array of JSON objects or JSON arrays."},"process_time":{"type":["null","array"],"items":{"type":"number"},"description":"Time for Spark to process the API call in `ms`. The elements of the array correspond to the input request records."},"warnings":{"type":["null","array"],"items":{"type":["null","array"],"items":{"type":["null","object"]}},"description":"Array of warnings. The elements of the array correspond to the input request records."},"errors":{"type":["null","array"],"items":{"type":["null","array"],"items":{"type":["null","object"]}},"description":"Array of errors. The elements of the array correspond to the input request records."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."}}}}}}}},"paths":{"/{tenant}/api/v4/execute":{"post":{"tags":["Execute API (v4)"],"summary":"Generic execute endpoint","description":"The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time.<br><br> If using an API key, the API key group must contain user groups that are also assigned to `Spark.SyncBatch.json` or `Spark.AllEncompassingProxy.json`.","operationId":"postv4Execute","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"$ref":"#/components/requestBodies/executeV4"},"responses":{"200":{"$ref":"#/components/responses/executeV4"}}}}}}
```

## Public API Generic execute endpoint

> The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time.\<br>\<br> If using an API key, the API key group must contain user groups that are also assigned to \`Spark.SyncBatch.json\` or \`Spark.AllEncompassingProxy.json\`.

```json
{"openapi":"3.1.0","info":{"title":"Spark OpenAPI specification","version":"0.1.0"},"tags":[{"name":"Execute API (v4)","description":"Execute multiple calculations from a Spark service. Supports synchronous batching enabling multiple requests to be submitted at the same time. See the [documentation](https://docs.coherent.global/spark-apis/execute-api/execute-api-v4) for more details.<br><br> 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](https://docs.coherent.global/spark-apis/batch-apis)."}],"servers":[{"url":"https://excel.{environment}.coherent.global","variables":{"environment":{"default":"myenvironmentname"}}}],"security":[{"bearerToken":[]},{"tenantName":[]},{"syntheticKey":[]}],"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token can be accessed from the user menu."},"tenantName":{"type":"apiKey","in":"header","name":"x-tenant-name","description":"Tenant name header required when using API key authentication."},"syntheticKey":{"type":"apiKey","in":"header","name":"x-synthetic-key","description":"API key instance."}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Tenant is part of your login URL and also available in the user menu.","schema":{"type":"string"}}},"requestBodies":{"executeV4":{"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":["null","array"],"items":{"oneOf":[{"type":"array","items":{},"description":"For JSON arrays format, the first row contains the name of the inputs in an array, and subsequent rows define the values for the corresponding records."},{"type":"object","description":"For JSON objects format, each element is an object containing key-value pairs that will be passed to the fields identified as Xinput in the workbook."}]},"description":"Array of input records."},"service":{"type":["null","string"],"description":"URI or `service_id` of the service being called."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"version_id of the requested service version. This will be resolved by Spark the quickest."},"version_by_timestamp":{"type":["null","string"],"anyOf":[{"type":"null"},{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Timestamp to resolve the service version. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert dates to ISO 8601. When call to a service is made using the `service_uri` or `service_id` this is used to determine the latest version of a service which have effective start and effective end dates that bound `transaction_date`. If omitted, the current date and time is used. If the `transaction_date` does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using `version` or `version_id` this field has no effect."},"output":{"type":["null","array"],"items":{"type":["null","string"]},"description":"Array of strings to denote the outputs to keep in the response. `*` can be used to identify wildcard characters. Alternatively direct refences to Excel ranges are possible. For `Neuron_v1.17.0` and later this can be enabled In Excel by adding a Named Range referenced to a cell called `xBuildParams`. The cell contents must contain `'--direct_addressing=true`. Furthermore if `#SparkFormulaValueVector` is added to these requests, only the calculated results would be returned."},"subservice":{"type":["null","string"],"description":"Comma separated string of subservice names. When this is not specified or set as `#Default#`, outputs not related to subservices are shown."},"source_system":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"correlation_id":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"call_purpose":{"type":["null","string"],"description":"Tag API call. Can be queried in _API Call History_."},"compiler_type":{"type":["null","string"],"description":"Calculation engine for the request. By default this uses the setting defined in _Service Documentation_ _Default service type_.","enum":["Neuron","XConnector"]},"manual_now":{"type":["null","integer"],"description":"Default behavior for Excel `NOW()` and `TODAY()` functions are to return the value based upon server time. If a [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) is provided, then that will be used to derive the current time and date instead."}}}}}}},"responses":{"executeV4":{"description":"OK","headers":{"X-RateLimit-Limit":{"schema":{"type":"number","description":"Spark rate limiter value."}},"X-RateLimit-Remaining":{"schema":{"type":"number","description":"Remaining calls for the rate limiter."}},"X-RateLimit-Reset":{"schema":{"type":"number","description":"[Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) representing when the rate limit is reset. Use [Timestamp converter](https://www.timestamp-converter.com/) to convert to ISO 8601."}}},"content":{"application/json":{"schema":{"properties":{"outputs":{"type":["null","array"],"items":{"oneOf":[{"type":"array","items":{},"description":"Array of JSON arrays."},{"type":"object","description":"Array of JSON objects."}]},"description":"Array of outputs. The elements of the array correspond to the input request records. Outputs will be formatted in a similar way to the inputs. The layout of outputs depends on whether the inputs comprised of an array of JSON objects or JSON arrays."},"process_time":{"type":["null","array"],"items":{"type":"number"},"description":"Time for Spark to process the API call in `ms`. The elements of the array correspond to the input request records."},"warnings":{"type":["null","array"],"items":{"type":["null","array"],"items":{"type":["null","object"]}},"description":"Array of warnings. The elements of the array correspond to the input request records."},"errors":{"type":["null","array"],"items":{"type":["null","array"],"items":{"type":["null","object"]}},"description":"Array of errors. The elements of the array correspond to the input request records."},"service_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`service_id` of the resolved service."},"version_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"`version_id` of the resolved service version."},"version":{"type":["null","string"],"description":"Resolved service version number."},"call_id":{"oneOf":[{"type":"null"},{"type":"string","format":"uuid"}],"description":"Universally unique identifier for this API call. This can be referenced in the _API Call History_."},"compiler_version":{"type":["null","string"],"description":"Calculation engine by Spark to process the request."},"correlation_id":{"type":["null","string"],"description":"Value from Request body."},"request_timestamp":{"oneOf":[{"type":"null"},{"type":"string","format":"date-time"}],"description":"Request timestamp."}}}}}}}},"paths":{"/{tenant}/api/v4/public/execute":{"post":{"tags":["Execute API (v4)"],"summary":"Public API Generic execute endpoint","description":"The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time.<br><br> If using an API key, the API key group must contain user groups that are also assigned to `Spark.SyncBatch.json` or `Spark.AllEncompassingProxy.json`.","operationId":"postv4PublicExecute","parameters":[{"$ref":"#/components/parameters/tenant"}],"requestBody":{"$ref":"#/components/requestBodies/executeV4"},"responses":{"200":{"$ref":"#/components/responses/executeV4"}}}}}}
```


---

# 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/spark-openapi-specification/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.