# Execute API (v3)

Execute the calculation from a Spark service.

Returns: Service execution response.

Each Spark service can be called to perform calculations by calling the Execute API. The `v3` specification of the Execute API is the version that is currently being used in the [API Tester](/navigation/api-tester.md).

{% code overflow="wrap" %}

```shellscript
## Depending on the desired reference parameter, different URI are available.
POST /{tenant}/api/v3/folders/{folder}/services/{service}/execute
POST /{tenant}/api/v3/service/{serviceId}
POST /{tenant}/api/v3/version/{versioId}
POST /{tenant}/api/v3/execute
POST /{tenant}/api/v3
POST /{tenant}/api/v3/public/folders/{folder}/services/{service}/execute
POST /{tenant}/api/v3/public/service/{serviceId}
POST /{tenant}/api/v3/public/version/{versionId}
POST /{tenant}/api/v3/proxy/{urlsuffix}
```

{% 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 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).
* `/{tenant}/api/v3` does not work with `x-synthetic-key` .

### 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><tr><td><code>folder</code> *</td><td>Folder associated with the request.</td></tr><tr><td><code>service</code> *</td><td>Service associated with the request.</td></tr><tr><td><code>serviceId</code> *</td><td><code>service_id</code> of the requested service. The latest service version will be referenced.</td></tr><tr><td><code>versionId</code> *</td><td><code>version_id</code> of the requested service version.</td></tr><tr><td><code>urlsuffix</code> *</td><td><a data-mention href="/pages/-MbpF0SlLUZiyM9EiqN0">/pages/-MbpF0SlLUZiyM9EiqN0</a> path.</td></tr></tbody></table>

### Request body <a href="#request-body" id="request-body"></a>

`Content-Type: application/json`

The easiest way to understand the `request_data` for your Spark service is experimenting in the [API Tester](/navigation/api-tester.md).

#### `request_data` <a href="#request_data" id="request_data"></a>

`inputs` is an object that contains key value pairs that will be passed to the fields identified as `Xinput` in the workbook.

*Representation of Spark inputs*

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>null</code></td><td>A null value is represented by <code>null</code>.</td></tr><tr><td>Single input</td><td><p>Example 1: <code>Xinput_Single_number</code>:</p><p><code>"Single_number": 1234.567</code></p><p>Example 2: <code>Xinput_Single_string</code>:</p><p><code>"Single_string": "Hello World!"</code></p></td></tr><tr><td>Range input</td><td><p>Example: <code>Xinput_Ranged_input</code> 2 column table of <code>E</code> and <code>F</code></p><p><code>E F</code></p><p><code>A 6</code></p><p><code>B 8</code></p><p>Would be referenced as:</p><p><code>"Ranged_input":</code></p><p> <code>[</code></p><p>  <code>{"E": "A", "F": 6},</code> </p><p>  <code>{"E": "B", "F": 8}</code></p><p><code>]</code><br><br><br>or alternatively using array notation:<br><code>"Ranged_input":</code> </p><p><code>[["E", "F"], ["A", 6], ["B", 8]]</code></p></td></tr></tbody></table>

*`inputs` data types*

<table data-full-width="false"><thead><tr><th>Type</th><th>Formatting description</th></tr></thead><tbody><tr><td><code>null</code></td><td>A null value is represented by <code>null</code>.</td></tr><tr><td><code>boolean</code></td><td>Boolean values are either <code>true</code> or <code>false</code>.</td></tr><tr><td><code>number</code></td><td><p>Use digits <code>0123456789</code> and with an optional <code>.</code> decimal separator as part of the API request only. Would not recommend using any strings enclosed symbols or separators such as <code>$</code> <code>%</code> <code>,</code> as these may potentially affect the calculation and interpretation of any Data Validation defined in the Excel file, however numeric strings are cast to numbers by Spark.</p><p>Example 1: Instead of <code>"$1,234.567"</code> use <code>1234.567</code></p><p>Example 2: Instead of <code>"8.5%"</code> use <code>0.085</code></p></td></tr><tr><td><code>string</code></td><td><p>Strings are enclosed with double quotation marks. An empty string is denoted as <code>""</code>.</p><p>Example: <code>"Hello world"</code></p></td></tr><tr><td><code>date</code></td><td><p>Dates are entered in <code>YYYY-MM-DD</code> format enclosed with double quotation marks.</p><p>Example: <code>"2021-12-31"</code></p></td></tr><tr><td><code>time</code></td><td><p>Times are entered in <code>hh:mm:ss</code> format enclosed with double quotation marks.</p><p>Example: <code>"23:59:59"</code></p></td></tr><tr><td><code>date and time</code></td><td><p>Dates and times are entered in <code>YYYY-MM-DD hh:mm:ss</code> format enclosed with double quotation marks. This format is consistent with Excel.</p><p>Example: <code>"2021-12-31 23:59:59"</code></p></td></tr></tbody></table>

#### `request_meta` <a href="#request_meta" id="request_meta"></a>

**Parameters to resolve Spark service versions**

Spark will use these parameters in order to resolve down to the most appropriate `version_id` to use for an API call. These parameters are not necessary if the URI contains sufficient information. 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_uri` last. It is possible that these 3 may refer to different services entirely but Spark will resolve the reference in the same order.
{% endhint %}

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>service_uri</code></td><td><p>Reference to service location in the format of <code>folders/{folder}/services/{service}</code>.</p><p>This does not specify the version of the service returned. This can be done so by including <code>transaction_date</code> or <code>version</code>.</p><p>Example: <code>folders/API V3/services/Sample API</code></p></td></tr><tr><td><code>service_id</code></td><td><p><code>service_id</code> of the requested service. This does not specify the version of the service returned. This can be done so by using <code>transaction_date</code> or <code>version</code>.</p><p>Example: <code>0c9deaad-bd33-49dd-9404-14f9303c531e</code></p></td></tr><tr><td><code>version</code></td><td><p>Semantic version number which corresponds to the version number shown in the Spark user interface: <code>{Major revision}.{Minor revision}.{Patch revision}</code>.</p><p>Used on conjunction with <code>service_uri</code> or <code>service_id</code>.</p><p>Example 1: <code>4.15.2</code><br><br><br></p><p>Example 2:  <code>1.4</code> take the latest version starting with <code>1.4.</code></p><p>Example 3: <code>1</code> take the latest version starting with <code>1.</code></p></td></tr><tr><td><code>version_id</code></td><td><p><code>version_id</code> of the requested service version.</p><p>This takes precedence over <code>service_uri</code>, <code>service_id</code>, <code>transaction_date</code>, <code>version</code>.</p><p>Example: <code>e5a86ccb-b53b-47c7-86e7-25c228b211f4</code></p></td></tr><tr><td><code>transaction_date</code></td><td><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 the <code>service_uri</code> 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>transaction_date</code>.</p><ul><li>If omitted, the current date and time is used.</li><li>If the <code>transaction_date</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></td></tr></tbody></table>

**Parameters for** [Neuron](/build-spark-services/neuron.md) **evaluation**

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>debug_solve</code></td><td>Boolean to return  <code>outputs.additional_outputs.solve_log</code> which contains the iterations for each <a data-mention href="/pages/-MbpBOp7u3sVV0FKH3dA">/pages/-MbpBOp7u3sVV0FKH3dA</a> in the service.<br>Example: <code>true</code></td></tr><tr><td><code>debug_xcall</code></td><td>Boolean to return  <code>outputs.additional_outputs.xcall_log</code> which contains the tracing for the <a data-mention href="/pages/7SrkjU0Gy85eBQjw6qoP">/pages/7SrkjU0Gy85eBQjw6qoP</a> used in the execution of the service.<br>Example: <code>true</code></td></tr><tr><td><code>manual_now</code></td><td><p>Default behavior for 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.</p><p>Example: <code>1650593119</code> would represent <code>2024-10-29T02:44:48</code></p></td></tr><tr><td><code>profile</code></td><td><p>Boolean to enable performance tracing.</p><p>See <a data-mention href="/pages/8K3cBGmifV9rvGdkMp6J">/pages/8K3cBGmifV9rvGdkMp6J</a> for more information.<br>Example: <code>true</code></p></td></tr><tr><td><code>random_seed</code></td><td>Number for random number generation seed. This ensures that each API call generates the same sequence of random numbers.<br>Example: <code>123</code></td></tr><tr><td><code>requested_output_regex</code></td><td><p>Regular expression string to denote the outputs to keep in the response. This is an advancement of <code>requested_output</code>. If both <code>requested_output</code> and <code>requested_output_regex</code> are specified, then an error will be raised.</p><p>Example 1: <code>solve</code> will return all outputs that contain <code>solve</code>.</p><p>Example 2: <code>^price_</code> will return all outputs that begin with <code>price_</code></p><p>Example 3: <code>a|c</code> matches outputs that are <code>a</code> or <code>c</code>.</p></td></tr><tr><td><code>show_max_calc_chain</code></td><td><p>When the debug build is used, this is used to identify the longest calculation chain.</p><p>See <a data-mention href="/pages/8K3cBGmifV9rvGdkMp6J">/pages/8K3cBGmifV9rvGdkMp6J</a> for more information.<br>Example: <code>true</code></p></td></tr><tr><td><code>top_n_profile</code></td><td><p>When the debug build is used, this is used to adjust the of number records returned from the performance tracing output.</p><p>See <a data-mention href="/pages/8K3cBGmifV9rvGdkMp6J">/pages/8K3cBGmifV9rvGdkMp6J</a> for more information.<br>Example: <code>25</code></p></td></tr></tbody></table>

**Parameters to control the response outputs**

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>requested_output</code></td><td><p>Array of strings to denote the <code>output</code>s to keep in the response. <code>*</code> can be used to identify wildcard characters.<br>Example 1: <code>["price*","*nut","Boeing7*7", "calc"]</code></p><p></p><p>Alternatively direct references to Excel ranges are possible.</p><p>For <a data-mention href="/pages/qc2ynJ5gnthNAqVrFQRg">/pages/qc2ynJ5gnthNAqVrFQRg</a> <code>1.7.0</code> to <code>1.16.0</code> <a data-mention href="/pages/-MbozEfHbi9LK1wc_fIw#service-details">/pages/-MbozEfHbi9LK1wc_fIw#service-details</a> <em>Direct addressing outputs enabled</em> when <code>TRUE</code> allows any cell of the Excel workbook to be returned as part of the <a data-mention href="/pages/nsJig8FRhYDL3hcSAwbt">/pages/nsJig8FRhYDL3hcSAwbt</a> response by specifying the <a data-mention href="/pages/nsJig8FRhYDL3hcSAwbt#request_meta">/pages/nsJig8FRhYDL3hcSAwbt#request_meta</a> <code>requested_outputs</code>.</p><p>For <code>Neuron_v1.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>.<br>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><p></p><p>For compatibility, the requested elements can also be provided in a comma separated list, Example 4: <code>"first,second,third"</code>.</p><p><br><code>Type3</code> behavior:</p><p>Single string that applies a “starts with” filter on the output objects.</p><p>Example 5: <code>price_</code> will only return all the outputs that begin with <code>price_</code>.</p></td></tr><tr><td><code>service_category</code></td><td><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></td></tr><tr><td><code>compiler_type</code></td><td>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>.<br>Example: <code>Neuron</code></td></tr><tr><td><code>array_outputs</code></td><td><p>This is a string list of <code>Xoutput</code> ranges to return in the JSON array format. Using <code>*</code> can be used to denote all of the outputs. See <a data-mention href="#response">#response</a>.</p><p>Example 1: <code>"*"</code></p><p>Example 2: <code>"list1, list2"</code></p></td></tr><tr><td><code>response_data_inputs</code></td><td>Boolean to enable the echo of <code>request_data.inputs</code> into <code>response_data.inputs</code>. This is useful for consuming systems that want to store and analyze the API request and response data together.</td></tr><tr><td><code>excel_file</code></td><td><p>When set to <code>true</code>, this returns a copy of the source Excel file with the <code>request_data</code> <code>inputs</code> populated into the <code>Xinput</code> cells. The output is the same as the <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0_</a> <em>Download as Excel (Legacy)</em>.</p><p><br>For security, the use of this feature with API keys can managed through <a data-mention href="/pages/ugc6Fepo88mURZUztmyG#assign-permissions-through-features-permissions">/pages/ugc6Fepo88mURZUztmyG#assign-permissions-through-features-permissions</a> and access to the <code>Spark.DownloadServiceByCallId.json</code> feature permission.<br><br>This is not a feature that is recommended for extensive use. Response times when using this feature will be inconsistent call to call due to the need to generate and populate the Excel file.</p></td></tr><tr><td><code>xreport_options</code></td><td>Parameters to control how <a data-mention href="/pages/-MbpB99a4-RzUY7txQjx">/pages/-MbpB99a4-RzUY7txQjx</a> are produced. See the above documentation link for more information.</td></tr><tr><td><code>xreport_options.produce_pdfs</code></td><td>Boolean to indicate whether to return the <code>Xreport</code> sheets as PDFs. Default is <code>true</code>.</td></tr><tr><td><code>xreport_options.multiple_docs</code></td><td><p>Boolean to indicate whether to return each <code>Xreport</code> sheet as a separate PDF. </p><ul><li>If no <code>xreport_options</code> are used in the request, the default is <code>true</code> .</li><li>If <code>xreport_options</code> are used in the request, the default is <code>false</code> .</li></ul></td></tr><tr><td><code>xreport_options.page_numbers</code></td><td>Boolean to indicate whether to include page numbers. Default is <code>true</code>.</td></tr></tbody></table>

**Parameters to tag a request**

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>call_purpose</code></td><td><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></td></tr><tr><td><code>source_system</code></td><td><p>Tag API Call. Can be queried in <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0_</a>.</p><p>Example: <code>mycicd</code></p></td></tr><tr><td><code>correlation_id</code></td><td><p>Tag API Call. Can be queried in <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0_</a>.</p><p>Example: <code>456</code></p></td></tr></tbody></table>

#### Submit tabular inputs as a JSON array

Extending upon [How to: Map inputs and outputs](/build-spark-services/map-inputs-and-outputs.md#map-a-single-multiple-cell-range-to-an-input-output) and [How to: Map inputs and outputs](/build-spark-services/map-inputs-and-outputs.md#csv-inputs-outputs), JSON arrays can also be used to pass in values for multiple cell table inputs. The array structure is more compact and can be easier to read for larger data sets.

*Example:*

If an `Xinput` table is defined as `Xinput_EMP` with the following structure:

| Name   | Age | Location |
| ------ | --- | -------- |
| Dinesh | 32  | Gota     |
| Sagar  | 25  | Nikol    |

Then, 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) can be formed using two methods:

<table><thead><tr><th>Default "records" JSON request format</th><th>JSON array format</th></tr></thead><tbody><tr><td>This is the default table representation shown in the <a data-mention href="/pages/-MbozNXhZ4wqfZ7uVWTp">/pages/-MbozNXhZ4wqfZ7uVWTp</a>.</td><td>Composing the tabular data using JSON arrays is more compact and easier to read.</td></tr><tr><td><pre class="language-json"><code class="lang-json">{
 "request_data": {
  "inputs": {
   "EMP": [{
     "Name": "Dinesh",
     "Age": 32,
     "Location": "Gota"
    },
    {
     "Name": "Sagar",
     "Age": 25,
     "Location": "Nikol"
    }
   ]
  }
 }
}
</code></pre></td><td><pre class="language-json"><code class="lang-json">{
 "request_data": {
  "inputs": {
   "EMP": [
    ["Name", "Age", "Location"],
    ["Dinesh", 32, "Gota"],
    ["Sagar", 25, "Nikol"]
   ]
  }
 }
}
</code></pre></td></tr></tbody></table>

#### Submit tabular inputs as a JSON array with multiple hierarchies

[Merged cells](https://support.microsoft.com/en-us/office/merge-and-unmerge-cells-5cbd15d5-9375-4540-907f-c673a93fcedf) in header rows are used to define additional hierarchy above the standard column headers shown in the previous example.

Extending the previous example of `Xinput_EMP`, the previous headings can be grouped into a subheading. `Personal` and `Professional` are merged cells that are included in the definition of `Xinput_EMP`.

<figure><img src="/files/5TbgLThQyIgdvahwiYGe" alt=""><figcaption></figcaption></figure>

* The merged cell is used to define a heading and subheading hierarchy. The `Personal` heading includes `Age` and `Location` subheadings. The `Professional` heading includes `Job` and `Industry` subheadings.
* Headings without subheadings should be defined in the row immediately above the first data row. In this example, the `Name` heading will be on the same hierarchy as `Personal` and `Professional`.
* The [API Tester](/navigation/api-tester.md) also supports the display of multiple row headers in the user interface.

The [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#request_data) can be formed using two methods:

<table data-full-width="false"><thead><tr><th>Default "records" JSON request format</th><th>JSON array format</th></tr></thead><tbody><tr><td>This is the default table representation. Heading objects include the nested subheadings.</td><td>The tabular data represented using JSON arrays is more compact and easier to read. Subcolumn headings are represented using <code>Heading.Subcolumn</code> notation.</td></tr><tr><td><pre class="language-json"><code class="lang-json">{
 "request_data": {
  "inputs": {
   "EMP": [{
     "Name": "Dinesh",
     "Personal": {
      "Age": 32,
      "Location": "Gota"
     },
     "Professional": {
      "Job": "Sr. QA",
      "Industry": "IT"
     }
    },
    {
     "Name": "Sagar",
     "Personal": {
      "Age": 25,
      "Location": "Nikol"
     },
     "Professional": {
      "Job": "QA",
      "Industry": "IT"
     }
    }
   ]
  }
 }
}
</code></pre></td><td><pre class="language-json"><code class="lang-json">{
 "request_data": {
  "inputs": {
   "EMP": [
    ["Name", "Personal.Age", "Personal.Location", "Professional.Job", "Profesional.Industry"],
    ["Dinesh", 32, "Gota", "Sr. QA"],
    ["Sagar", 25, "Nikol", "QA"]
   ]
  }
 }
}
</code></pre></td></tr></tbody></table>

### Sample request <a href="#request" id="request"></a>

```json
{
  "request_data": {
    "inputs": {
      "Chain_a": 4,
      "Chain_b": 2,
      "Range_EF": [
        {
          "E": "A",
          "F": 6
        },
        {
          "E": "B",
          "F": 8
        }
      ],
      "Single_A": 2,
      "Single_B": 4,
      "Single_C": "sample text",
      "Single_D": "2021-10-18",
      "Single_J_Error": "Z",
      "Solve_y_target": 0,
      "Single_XJ_In_G": 3,
      "Single_XJ_In_H": "",
      "Single_XJ_In_I": 2,
      "REPORT1": {
        "FileName": null
      }
    }
  },
  "request_meta": {
    "service_uri": "folders/API V3/services/Sample API Full",
    "service_id": "",
    "version": "1.0.0",
    "version_id": "d5b2b3b3-8d79-41b1-a9c3-3d9652687204",
    "transaction_date": "2021-12-29T06:15:28.583Z",
    "call_purpose": "Spark - API Tester",
    "source_system": "SPARK",
    "correlation_id": "",
    "requested_output": "",
    "service_category": "#Default#",
    "compiler_type": "Neuron"
  }
}
```

### Response headers <a href="#response-header" id="response-header"></a>

Response headers of note

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>spark_total_time</code></td><td><p>The time it took for Spark to process the inputs, perform the calculation, execute any <code>Ximage</code>, <code>Xreport</code>, <code>Xsolve</code> parameters in <code>ms</code>. This does not include any transit time.</p><p>Example: <code>50</code></p></td></tr><tr><td><code>X-RateLimit-Limit</code></td><td>Spark rate limiter value.<br>Example: <code>600</code></td></tr><tr><td><code>X-RateLimit-Remaining</code></td><td>Remaining calls for the rate limiter.<br>Example: <code>590</code></td></tr><tr><td><code>X-RateLimit-Reset</code></td><td><a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch time</a> representing when the rate limit is reset. Use <a href="https://www.timestamp-converter.com/">Timestamp converter</a> to convert to ISO 8601.<br>Example: <code>1768925455</code></td></tr></tbody></table>

### Response body <a href="#response-body" id="response-body"></a>

`Content-Type: application/json`

#### `status` <a href="#status" id="status"></a>

`success` is returned when the API is able to provide a calculated response

`error` is returned if there is an issue providing an API response.

#### `response_data` <a href="#response_data" id="response_data"></a>

**`inputs`**

Inputs from the request will be returned in the response if the [#request\_meta](#request_meta "mention") `response_data_inputs` is `true`.

**`outputs`**

Outputs generally follow the same conventions as inputs described in [#request\_data](#request_data "mention"). It is recommended to test and evaluate the response outputs before finalizing any integration.

* Ranges are dynamically sized on the output. For any ranged values, if a row is completely empty (null) at the *end* of the dataset, it will not be returned. For example, if an `Xoutput` has been defined as `6` rows but only the first `4` rows have data, then only `4` rows will be returned as part of the API response.

<table data-full-width="false"><thead><tr><th>Type</th><th>Formatting description</th></tr></thead><tbody><tr><td><code>null</code></td><td>For any <code>Xjoutput</code> this will return as <code>""</code>.</td></tr><tr><td><code>date and time</code></td><td><p>Dates and times are returned in <code>YYYY-MM-DDThh:mm:ss</code> format enclosed with double quotation marks. This format is consistent with ISO 8601.</p><p>Example: <code>"2021-12-31T23:59:59"</code></p></td></tr></tbody></table>

**`warnings`**

Warnings are issues that may potentially affect the correct calculation of the response.

A common reason for warnings is that an input value was not provided as part of the `request_data` and therefore a default value was used.

```json
"warnings": [
  {
    "source_path": "Default Values",
    "message": "Input parameter(s) missing. API request using the Default Values."
  }
]
```

**`errors`**

Common error messages:

* `"message": "INVALID_TOKEN"` accompanied by HTTP status code `401 Unauthorized`. This likely refers to a security token that is expired.
* `"message": "unknown error. reason: INVALID_REQUEST_PAYLOAD."` occurs if the API response body is not structured in the correct manner (e.g. using the older V1 request format).
* `"message": "unknown error. reason: NO_ACTIVE_VERSION."` occurs when calling a service version beyond its effective start and effective end dates.
* `"message": "unknown error. reason: Object reference not set to an instance of an object.."` may arise when using an incorrect combination of `service_uri` `service_id` `version` `version_id`.

Errors may also relate to issues from data validation where the `request_data` includes values that fail the data validation as defined in Excel or raised using the `Xvalidate` formula. These are set as errors as they indicate that the calculated response data may not be correct.

```json
"errors": [
  {
    "error_category": "validation_error",
    "error_type": "error.VALIDATION",
    "additional_details": "SimpleServiceAplusB",
    "source_path": "$.Input.A",
    "message": "Input Not Valid"
  },
  {
    "source_path": "$.Input.Xvalidate1",
    "error_category": "validation_error",
    "error_type": "error.VALIDATION",
    "message": "I am an Xvalidate error",
    "additional_details": "Sample API Full"
  }
]
```

#### `response_meta` <a href="#response_meta" id="response_meta"></a>

These are response metadata used to provide information on how the request was processed.

<table data-full-width="false"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>system</code></td><td><p>System that processed the request.</p><p>Example: <code>SPARK</code></p></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><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>process_time</code></td><td><p>Time for Spark to process the API call in <code>ms</code>.</p><p>Example: <code>30</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_type</code></td><td><p>Calculation engine used by Spark to process the request.</p><p>Example: <code>Neuron</code></p></td></tr><tr><td><code>compiler_version</code></td><td><p>Compiler version of this service version.</p><p>Example: <code>1.25.0</code></p></td></tr><tr><td><code>source_hash</code></td><td><code>null</code></td></tr><tr><td><code>engine_id</code></td><td><p>Hash generated for this service.</p><p>Example: <code>64AFC7C321E5B97BAB090371DF1E9580</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>response_data_inputs</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>array_outputs</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>random_seed</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>show_max_calc_chain</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>profile</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>trace</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>top_n_profile</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>parameterset_version_id</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>debug_xcall</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>debug_solve</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr><tr><td><code>manual_now</code></td><td>Value from <a data-mention href="#request-body">#request-body</a>.</td></tr></tbody></table>

#### Return tables as JSON arrays <a href="#response" id="response"></a>

Multiple cell table outputs defined as `Xoutput` can also be returned using JSON arrays as part of the  [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#response_data). To output all tables in the JSON array format, include the parameter `"array_outputs": "*"` in the [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#request_meta).

Below is an example of a multiple-cell range defined as `Xoutput_Packaging` and a comparison between the default and JSON array formats.

### Sample response <a href="#response" id="response"></a>

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

```json
{
  "response_data": {
    "outputs": {
      "CSV1": "\"A\",\"B\",\"C\"\n\"1\",\"2\",\"3\"\n",
      "Chain_a": 4,
      "Chain_b": 2,
      "Range_EF_function": [
        {
          "E": "AB",
          "F": 48
        }
      ],
      "Single_AB_function": 20,
      "Single_C_function": "SAMPLE TEXT",
      "Single_D_function": "2022-10-18",
      "Solve_x_calculated": 5.3579474132655,
      "Single_XJ_Out_G": 3,
      "Single_XJ_Out_H": "",
      "Single_XJ_Out_I": 2,
      "Solve1": {
        "TargetValue": "0",
        "ByChangingCellValue": "5.357947413265504",
        "Comments": "Goal was reached on iteration 9."
      },
      "REPORT1": {
        "PDFUrl": "https://excel.myenvironment.coherent.global/67a1a340-3f06-4db1-a4b8-316757d03d07.pdf",
        "PDFName": "67a1a340-3f06-4db1-a4b8-316757d03d07.pdf",
        "DocumentGenerationTime": "23",
        "PDFGenerationTime": "7"
      }
    },
    "warnings": [],
    "errors": [
      {
        "error_category": "validation_error",
        "error_type": "error.VALIDATION",
        "additional_details": "SimpleServiceAplusB",
        "source_path": "$.Input.A",
        "message": "Input Not Valid"
      },
      {
        "error_category": "validation_error",
        "error_type": "error.VALIDATION",
        "additional_details": "Sample API Full",
        "source_path": "$.Input.Xvalidate1",
        "message": "I am an Xvalidate error"
      }
    ]
  },
  "response_meta": {
    "service_id": "4bf0af24-0a24-49f1-bd02-c2a343eb8246",
    "version_id": "d5b2b3b3-8d79-41b1-a9c3-3d9652687204",
    "version": "1.0.0",
    "process_time": 2,
    "call_id": "372167af-ae77-4298-8f59-f45c0f98c4fe",
    "compiler_type": "Neuron",
    "compiler_version": "1.0.0",
    "source_hash": null,
    "engine_id": "B72FD22D775D5A9FA10BCFF183369BCB",
    "correlation_id": "",
    "system": "SPARK",
    "request_timestamp": "2021-12-29, 06:15:32 GMT+00:00"
  }
}
```


---

# 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-v3.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.