# API_CALL
URL: https://docs.valsight.ai/api-call/
Description: Enables Valsight to interact with external applications by making a POST call to a designated URL and returning the result to the Valsight model.
**Category:** [Data access](/data-access/)

> This function requires a separate subscription and is not available in all Valsight instances.

## Overview

The **API\_CALL** function **sends node values to an external service** over an HTTP POST request and returns the service's response to the model as a node.

Use this function when a calculation must run on an external system and the result should flow back into the model.

## Syntax

`API_CALL(url, ['inputNodes'], ["resultLevels"] [, format, version, message, timeout])`

**Example usage:** `API_CALL("https://example.com/sum", ['Node A', 'Node B'], ["Year", "Country"])`

## Parameters

| Parameter        | Description                                                                                                                     | Type                    | Required | Default |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------- | ------- |
| **url**          | The endpoint the POST request is sent to. Must match the allow-list configured by an administrator (see Availability & limits). | String                  | Yes      | --      |
| **inputNodes**   | List of nodes, in square brackets, whose values are sent with the request.                                                      | List of node references | Yes      | --      |
| **resultLevels** | List of levels, in square brackets, that Valsight expects back from the service. These define the shape of the returned node.   | List of level names     | Yes      | --      |
| **format**       | Data format of the response. Only `JSON` is supported.                                                                          | String                  | No       | `JSON`  |
| **version**      | Version identifier sent with the request.                                                                                       | String                  | No       | --      |
| **message**      | Free-text message sent with the request.                                                                                        | String                  | No       | --      |
| **timeout**      | Time limit for the call, in seconds. If the service does not respond in time, the request is cancelled.                         | Number                  | No       | --      |

## Output shape

| Aspect         | Behavior                                                                        |
| -------------- | ------------------------------------------------------------------------------- |
| Dimensionality | The levels listed in `resultLevels`.                                            |
| Values         | Taken from the service's response, parsed from the Valsight Table JSON payload. |
| Row count      | Determined by the rows the service returns.                                     |

## Watch out

* The response must follow the Valsight Table JSON structure, otherwise it cannot be converted into a node. See [Response format](#response-format).
* Unknown keys in the response are ignored; only known keys are validated.
* If `response_status` is `ERROR`, Valsight surfaces the text in `error_msg` and returns no data.

## Availability & limits

API\_CALL is off by default and is controlled by global feature flags that an administrator configures:

* **`featureFlags.apiCall.allowedUrlsRegex`**: a Java regular expression of permitted URLs. Empty by default, which allows no URLs, so an administrator must set it before the function can be used.
* **`featureFlags.apiCall.maxRowsToSend`**: maximum combined number of rows across the input nodes per request. Default `150000`.
* **`featureFlags.apiCall.maxMbsToReturn`**: maximum response size read, in megabytes. Default `24`.

## Response format

Valsight validates a known set of keys in the response and ignores any others:

* `response_status`: `SUCCESS` or `ERROR`. On `ERROR`, Valsight displays the message in `error_msg`.
* `output`: the returned node, in the Valsight Table JSON structure.

An example response:

```
{
  "format": "JSON",
  "version": "1",
  "function_name" : "simple_plus",
  "response_status": "SUCCESS",
  "warning_msg": "",
  "error_msg": "",
  "output" : {
        "version": "1",
        "columnMetadata": [
            {
                "name": "Year",
                "columnType": "level",
                "levelId": 1
            },
            {
                "name": "measure",
                "columnType": "measure"
            }
        ],
        "rowData": [
            ["2015","50"],
            ["2016","100"],
            ["2017","150"],
            ["2018","200"]
        ]
    }
}
```

## Example

This example sends two nodes to a service that adds them and returns the sum per Year and Country.

**Input node:** `'A'`

| Year | Country | Revenue |
| ---- | ------- | ------- |
| 2025 | DE      | 100     |
| 2026 | DE      | 200     |
| 2027 | DE      | 300     |
| 2028 | DE      | 400     |
| 2029 | DE      | 500     |

**Input node:** `'B'`

| Year | Country | Revenue |
| ---- | ------- | ------- |
| 2025 | DE      | 350     |
| 2026 | DE      | 400     |
| 2027 | DE      | 450     |
| 2028 | DE      | 500     |
| 2029 | DE      | 550     |

**Formula:** `API_CALL("https://externalServer.com/sumTwoNodes", ['Node A', 'Node B'], ["Year", "Country"])`

Valsight sends nodes A and B and requests the levels Year and Country back. When the service responds successfully, the result is:

| Year | Country | Revenue |
| ---- | ------- | ------- |
| 2025 | DE      | 450     |
| 2026 | DE      | 600     |
| 2027 | DE      | 750     |
| 2028 | DE      | 900     |
| 2029 | DE      | 1050    |

## Related

| Function       | When to use instead                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| [DATA](/data/) | When the external data is already uploaded as a data table, reference it directly instead of calling a live service. |