Runtime Parameter overrides
10.14.0.cl
Cloud (Latest)
10.13.0.cl
Cloud
10.12.0.cl
Cloud
10.10.0.sw
Software (Latest)
10.1.0.sw
Software

Runtime Parameter overrides

Parameters in ThoughtSpot are typically used for "what-if" analysis, scenario planning, or to personalize data views without modifying the underlying data object. You can create Parameters in a Model and integrate them into formulas, filters, data queries, and Liveboards. You can also use Parameters within formulas when querying your data via Search, Liveboards, Answers, or Spotter sessions.

Overview🔗

Runtime parameters in ThoughtSpot are dynamic values that can be set or overridden at the time of accessing a Liveboard, Answer, visualization, or Spotter session.

Runtime parameters can be applied using one of the following options:

  • Via Visual Embed SDK
    Use the runtimeParameters property in the Visual Embed SDK for embedded objects.
    The SDK also provides host events to update Parameters.

  • Via REST APIs
    Use REST API requests to apply runtime overrides on Liveboard, Answer, or visualization data.

  • Via URL query parameters
    Pass Parameter name and values as query parameters in the URL.

When applied, runtime parameters override the default or saved Parameter values for the user session or API call, and the changes are reflected in the resulting data and visualizations, but not saved to the object itself.

Supported data types🔗

You can apply runtime Parameters on the following data types:

  • VARCHAR

  • BIGINT

  • INT

  • FLOAT

  • DOUBLE

  • BOOLEAN

  • DATE

  • DATE_TIME

  • TIME

Important

For the DATE and DATE_TIME data types, you must provide the date and time values in the Epoch time format. The Epoch time is also referred to as POSIX or Unix time. Epoch time is an integer value representing the number of seconds elapsed since 1 JAN 1970 00:00:00 UTC. You may have to convert time zones to calculate the appropriate timestamp.

For example, if you want to filter data for 2020-05-22, you can specify the date value in the Epoch time format as 1590192000, or use the following JavaScript method to calculate the timestamp:

new Date('2020-05-22').getTime() / 1000

Apply Parameter overrides in Visual Embed SDK🔗

The Visual Embed SDK supports runtime Parameter overrides on embedded Liveboards, Answers, and Spotter-generated answers. Before applying a Parameter override on any object, make sure the Parameters and associated formulas are configured in the data Model used for generating charts and tables.

The following examples show how to apply multiple runtime filters in the embed code:

const liveboardEmbed = new LiveboardEmbed('#tsEmbed', {
    ... // other embed view config
    liveboardId: '543619d6-0015-4667-b257-eff547d13a12',
    runtimeParameters:[{
        name: "Date List Param",
        value: 1662361200
    },
    {
        name: "Integer Range Param",
        value: 5
    }]
});
const spotterEmbed = new SpotterEmbed('#tsEmbed', {
    ... // other embed view config
    worksheetId: "cd252e5c-b552-49a8-821d-3eadaa049cca",
    searchOptions: {
        searchQuery: 'sales data for west coast',
    },
    runtimeParameters: [{
            name: "Date List Param",
            value: 1662361200
        },
        {
            name: "Integer Range Param",
            value: 5
        }
    ]
});

Note the following behavior in Spotter embedding:

  • Saving or pinning an answer does not retain the Parameter. Instead, only the Parameter value is stored.

  • In future releases, saved chats will also not retain the Parameter.

  • Users can see the Parameter value in formulas in edit mode, but only the value set for them will be visible.

  • Parameter values cannot be changed during a conversation session and may result in unintended effects.

  • If a user adds a Parameter to an answer through the edit flow, Spotter may drop this Parameter and any formulas using it in follow-up interactions. This means Parameters added in this way are not guaranteed to persist in subsequent conversational steps.

  • In Spotter embed, updating Parameters via host and embed events may not work as desired.

Adjust Parameter values using a host event🔗

After loading the embedded object, Parameters can be adjusted using the HostEvent.UpdateParameters event.
Developers can also set the Parameter chip visibility using the isVisibleToUser attribute in the HostEvent.UpdateParameters event payload.

liveboardEmbed.trigger(HostEvent.UpdateParameters, [{
        name: "Date List Param",
        value: 1656914873,
        isVisibleToUser: false
    },
    {
        name: "Integer Range Param",
        value: 10,
        isVisibleToUser: false
    }
])
Important

Although the SDK allows setting isVisibleToUser for multiple Parameters in a single HostEvent.UpdateParameters request, we do not recommend passing different values of isVisibleToUser in a single HostEvent.UpdateParameters request. If you need to set different isVisibleToUser values for different Parameters, make separate HostEvent.UpdateParameters requests for each distinct override.

Show or hide Parameter chips in embedded sessions🔗

Parameter values can be set or overridden using the following methods:

  • The runtimeParameters property in ThoughtSpot’s Visual Embed SDK.
    Hides Parameter chips by default, but the Parameter values are applied to visualizations.

  • The HostEvent.UpdateParameters event in the Visual Embed SDK.
    Allows overriding Parameter values and setting isVisibleToUser to show or hide the chip. By default, isVisibleToUser is set to false, so the chip is hidden, but the Parameter value is applied to visualizations.

  • URL Parameter override (without SDK)
    Hides Parameter chips by default, but the value is applied to visualizations.

The following table describes parameter chip behavior in the embedded view:

Parameter chip stateInitialization methodUpdate via HostEvent.UpdateParameters?Can change chip visibility?

Visible

No overrides applied

Possible

Yes. By default, the chip will be hidden after an update via HostEvent.UpdateParameters. To retain chip visibility after an override, you must explicitly set isVisibleToUser to true in your HostEvent.UpdateParameters request.

Hidden

Overrides applied via runtimeParameters in the Visual Embed SDK

Possible

No

Hidden

Overrides applied via URL parameters

Possible

No

Hide Parameter chips🔗

To hide the parameter chip, initialize a Parameter override before loading the ThoughtSpot page using one of the following methods:

  • The runtimeParameters object in the Visual Embed SDK

  • By applying a Parameter override directly in the URL

You can also set the isVisibleToUser attribute to false in the HostEvent.UpdateParameters event payload to hide the chip after the Parameter update.

liveboardEmbed.trigger(HostEvent.UpdateParameters, [{
    name: "Integer Range Param",
    value: 10,
    isVisibleToUser: false
}])

Show Parameter chips🔗

To show a Parameter chip, update the Parameter value using HostEvent.UpdateParameters after the page has loaded.

Note that if a Parameter chip was hidden during initialization via runtimeParameters in the Visual Embed SDK or via URL query parameters, or if it was hidden by setting isVisibleToUser to false in a previous HostEvent.UpdateParameters request, then it will remain permanently hidden for the lifetime of the embed. Once hidden, a parameter cannot be made visible again unless you create a new embed object.

However, if a Parameter chip is visible after initialization, you can retain its state by setting isVisibleToUser to true:

liveboardEmbed.trigger(HostEvent.UpdateParameters, [{
    name: "Integer Range Param",
    value: 10,
    isVisibleToUser: true
}])

Apply Parameter overrides via REST API🔗

You can apply Parameter overrides to a Liveboard or Answer using REST v1 and v2 API endpoints. Before applying a Parameter override on a Liveboard or Answer object, ensure that the Parameters are configured in the source Model.

REST API v2🔗

You can apply runtime Parameters when sending an API request to the following v2 API endpoints:

POST /api/rest/2.0/searchdata (Search data)

Allows searching data from a given data source.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "query_string": "[revenue][color]",
  "logical_table_identifier": "540c4503-5bc7-4727-897b-f7f4d78dd2ff",
  "runtime_param_override": {
    "param1": "Date List Param",
    "paramVal1": 1672567200,
    "param2": "Integer Range Param ",
    "paramVal2": 5
  }
}'
POST /api/rest/2.0/metadata/liveboard/data (Fetch Liveboard data)

Gets data from the Liveboard specified in the API request.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125",
  "runtime_param_override": {
    "param1": "Date List Param",
    "paramVal1": 1672567200,
    "param2": "Integer Range Param ",
    "paramVal2": 5
  }
}'
POST /api/rest/2.0/metadata/answer/data (Fetch Answer data)

Gets data from a saved Answer.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "0fb54198-868d-45de-8929-139b0089e964",
  "runtime_param_override": {
    "param1": "Double List Param",
    "paramVal1": 0.5,
    "param2": "Date Param",
    "paramVal2": 1696932000
  }
}'
POST /api/rest/2.0/report/liveboard (Export Liveboard Report)

Gets data from a Liveboard in the file format specified in the API request.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125",
  "file_format": "PNG",
  "runtime_param_override": {
    "param1": "Date List Param",
    "paramVal1": 1672567200,
    "param2": "Integer Range Param ",
    "paramVal2": 5
  }
}'
POST /api/rest/2.0/report/answer (Export Answer Report)

Gets data from a saved Answer in the file format specified in the API request.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "0fb54198-868d-45de-8929-139b0089e964",
  "file_format": "PNG",
  "runtime_param_override": {
    "param1": "Double List Param",
    "paramVal1": 0.5,
    "param2": "Date Param",
    "paramVal2": 1696932000
  }
}'

REST API v1🔗

You can apply runtime Parameters when sending an API request to the following v1 Data API endpoints:

  • /tspublic/v1/pinboarddata (Liveboard data API)

  • /tspublic/v1/searchdata (Search data API)

Liveboard data🔗

To apply overrides to a Liveboard via REST API, add Parameters to the Liveboard data API request URL as shown in the example here:

https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=86bedf72-c718-49cc-9f49-6e8870233f35&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&param1=Double%20list%20param&paramVal1=0

If the API request is valid, overrides are applied to the Liveboard data, and ThoughtSpot returns the requested data in the API response.

{
    "adfaa348-755b-4b95-94ff-220c94c0c8b6": {
        "columnNames": [
            "Ship Mode",
            "Total Tax",
            "Adjusted Tax"
        ],
        "data": [
            [
                "fob",
                7,
                0.0
            ],
            [
                "mail",
                2,
                0.0
            ]
        ],
        "samplingRatio": 1.0,
        "totalRowCount": 2,
        "rowCount": 2,
        "pageSize": 100000,
        "offset": 0,
        "name": "Parameters Answer"
    }
}

Search data🔗

To apply overrides on an Answer obtained from a new search query, append the Parameter attributes to the search data API request URL as shown here:

https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?query_string=%20%5BTax%5D%5BShip%20Mode%5D&data_source_guid=540c4503-5bc7-4727-897b-f7f4d78dd2ff&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&param1=Double%20list%20param&paramVal1=0

Add additional Parameters🔗

You can add additional Parameters in the URL by incrementing the number for each Parameter attribute; for example, param1, param2, paramVal1, paramVal2, and so on. To add additional overrides, specify the values by separating them with an ampersand (&) as shown in the examples here:

URL
https://{ThoughtSpot-host}/?param1=double%20list%20param&paramVal1=0&param2=double%20param&paramVal2=0#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a
REST API request
https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&param1=double%20list%20param&paramVal1=0&param2=double%20param&paramVal2=0

Apply runtime overrides via URL query parameters🔗

You can apply overrides to Parameter values at runtime and visualize data with the adjusted values. Like runtime filters, you can append the Parameter attribute to the object URLs and modify the resulting output.

For example, if you want to override the value of the inflation Parameter on a Liveboard or Answer, add the Parameters to the object URL as shown in these examples:

Liveboard
https://{ThoughtSpot-host}/?param1=Discount&paramVal1=0.25#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a
Saved Answer
https://{ThoughtSpot-host}/?param1=Discount&paramVal1=0.25#/saved-answer/3e84d95c-986e-4154-8362-3807906dad50
Search data
https://{ThoughtSpot-host}/?param1=Discount&paramVal1=0.25#/answer/
Important

ThoughtSpot returns an error if an object URL with Parameter attributes exceeds 2000 characters.

Parameters and JWT tokens🔗

Parameters work differently when used in JWT tokens to secure values for users. Setting a Parameter value via a JWT token will not hide the Parameter value by default. It lets you display a placeholder value on the Parameter chip, for example “Secured”, to indicate that the Parameter is used for security purposes. Note that the placeholder Parameter value is the default value set in your Parameter. Business users will see this value on the Parameter chip. However, the value of the parameter being used in the data displayed will be the one passed via the JWT token.

Regardless of the user’s interaction with the Parameter chip, Parameter values initiated via the JWT token cannot be overridden through the UI, to guarantee its use for security purposes only.

ThoughtSpot recommends hiding the Parameter chip while using a JWT token to minimize confusion. To do so, set the is_hidden flag to true in the Model TML for all Parameter columns that you wish to hide from ThoughtSpot’s user interface:

Parameter hidden

Is the Parameter value passed via a JWT?Is the is_hidden property enabled for the Parameter in the Model?Parameter chip behavior

Yes

No

The Parameter chip is visible and shows the parameter’s default value. It uses the Parameter value defined in the JWT in the data. User interactions with the filter chip will be ignored due to Parameter value defined via JWT token being locked.

Yes

Yes

The Parameter chip will be hidden. Uses the Parameter value defined in the JWT token.

© 2025 ThoughtSpot Inc. All Rights Reserved.