API_CALL

In Data access

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

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: API_CALL("https://example.com/sum", ['Node A', 'Node B'], ["Year", "Country"]).

If you are implementing the receiving service, see Build a service for API_CALL for a worked example.

Parameters

urlStringRequired

The endpoint the POST request is sent to. Must match the allow-list configured by an administrator (see Availability & limits).

inputNodesList of node referencesRequired

List of nodes, in square brackets, whose values are sent with the request.

resultLevelsList of level namesRequired

List of levels, in square brackets, that Valsight expects back from the service. These define the shape of the returned node.

formatStringOptional

Data format of the response. Only JSON is supported. Default: JSON.

versionStringOptional

Version identifier sent with the request. Passed through untouched.

messageStringOptional

Free-text message sent with the request. Passed through untouched.

timeoutNumberOptional

Time limit for the call, in seconds. If the service does not respond in time, the request is cancelled. Default: 30.

The four optional arguments are positional and nested: to pass timeout you must also pass format, version and message before it. There is no way to skip an earlier one.

Output shape

Dimensionality

Per dimension, the deepest level listed in resultLevels. Listing both Year and Quarter produces a node on Quarter alone.

Values

Taken from the service’s response, parsed from the Valsight Table JSON payload.

Row count

Determined by the rows the service returns.

The response is validated against every level named in resultLevels, in the order written, even where the node itself ends up on fewer levels.

Watch out

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 all input nodes per request. Default 150000.
• featureFlags.apiCall.maxMbsToReturn: maximum response size read, in megabytes. Default 24.

Request format

Valsight sends one POST request with Content-Type: application/json and this body:

An example request body for API_CALL("https://example.com/sum", ['Node A'], ["Year", "Country"], "JSON", "1", "a message"):

{
  "inputs": {
    "0": {
      "version": "1",
      "columnMetadata": [
        {"name": "Year",    "columnType": "level", "levelId": 118},
        {"name": "Country", "columnType": "level", "levelId": 101},
        {"name": "measure", "columnType": "measure"}
      ],
      "tableMetadata": {"tableType": "FACT", "tableName": "Input 0"},
      "rowData": [["2025", "DE", "100"], ["2026", "DE", "200"]]
    }
  },
  "result_levels": "[Year, Country]",
  "message": "a message",
  "version": "1",
  "format": "JSON",
  "maximum_mbs_to_return": "24"
}

{
  "inputs": {
    "0": {
      "version": "1",
      "columnMetadata": [
        {"name": "Year",    "columnType": "level", "levelId": 118},
        {"name": "Country", "columnType": "level", "levelId": 101},
        {"name": "measure", "columnType": "measure"}
      ],
      "tableMetadata": {"tableType": "FACT", "tableName": "Input 0"},
      "rowData": [["2025", "DE", "100"], ["2026", "DE", "200"]]
    }
  },
  "result_levels": ["Year", "Country"],
  "message": "a message",
  "version": "1",
  "format": "JSON",
  "maximum_mbs_to_return": "24"
}

Because message and version are passed through untouched, they are a convenient way to switch behaviour in the service from the formula, without changing the interface.

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_message. The key may be omitted entirely; only an unrecognised value is an error.
• error_message: the text shown to the user when response_status is ERROR.
• output: the returned node, in the Valsight Table JSON structure.

The output cube must carry exactly the levels named in resultLevels, plus a measure column. The most robust way to build its columnMetadata is to copy the entries from an input cube, because they carry the levelId values Valsight uses to map values back onto its dimensions.

An example response:

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

Errors

Every message below is shown on the node, prefixed with API_CALL -.

Examples

Sending two nodes to a service that adds them

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

Input node: 'A'

Input node: 'B'

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

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

Switching behaviour from the formula

This example uses message to pick a mode in the service without changing the interface.

Formula: API_CALL("https://externalServer.com/optimize", ['Volume'], ["Country"], "JSON", "1", "integer")

The service receives "message": "integer" and can branch on it, for instance to run an integer rather than a continuous optimisation. Passing message requires passing format and version first, because the optional arguments are positional.

Related

DATA

When the external data is already uploaded as a data table, reference it directly instead of calling a live service.