The query assistance APIs help users find the appropriate dataset for a given query string, suggest what questions can be asked, and return example questions. These APIs are specifically designed to improve data literacy for users who may not be familiar with the underlying data, making it easier for them to explore and analyze data effectively.
For information about creating a conversation session, see Spotter agent conversation APIs.
The POST /api/rest/2.0/ai/data-source-suggestions API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata object referenced in the response.
| Parameter | Description |
|---|---|
| Required. Specify one of the following attributes to set the metadata context:
|
| String. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. |
| Integer. Sets a limit on the number of sub-questions to return in the response. Default is 5. |
| Boolean. When set to |
| Additional context to guide the response. Define the following attributes as needed: |
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"metadata_context": {
"data_source_identifiers": [
"cd252e5c-b552-49a8-821d-3eadaa049cca"
]
},
"query": "Net sales of Jackets in west coast",
"limit_relevant_questions": 3
}'If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning.
{
"relevant_questions": [
{
"query": "What is the trend of sales by type over time?",
"data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca",
"data_source_name": "(Sample) Retail - Apparel"
},
{
"query": "Sales by item",
"data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca",
"data_source_name": "(Sample) Retail - Apparel"
},
{
"query": "Sales across regions",
"data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca",
"data_source_name": "(Sample) Retail - Apparel"
}
]
}The returned results include metadata such as:
confidence
A float indicating the Model’s confidence in the relevance of each recommendation.
details
The data source ID, name, and description for each recommended data source.
reasoning
Reason provided by the LLM to explain why each data source was recommended.
The /api/rest/2.0/ai/relevant-questions/ API endpoint breaks down a user-submitted query into relevant sub-questions. It accepts the original query and optional additional context, then generates a set of related questions to help users explore their data comprehensively.
During agentic interactions, this API can be used as an integrated tool to decompose user queries and suggest relevant questions for a specific data context. REST clients can also call this API directly to fetch relevant questions via a POST request.
| Parameter | Description |
|---|---|
| Required. Specify one of the following attributes to set the metadata context:
|
| String. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. |
| Integer. Sets a limit on the number of sub-questions to return in the response. Default is 5. |
| Boolean. When set to |
| Additional context to guide the response. Define the following attributes as needed:
|
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {AUTH_TOKEN}' \
--data-raw '{
"metadata_context": {
"data_source_identifiers": [
"cd252e5c-b552-49a8-821d-3eadaa049cca"
]
},
"query": "Net sales of Jackets in west coast",
"limit_relevant_questions": 3
}'If the request is successful, the API returns a set of questions related to the query and metadata context in the relevant_questions array. Each object in the relevant_questions array contains the following fields:
query
A string containing the natural language (NL) sub-question.
data_source_identifier
GUID of the data source object.
data_source_name
Name of the associated data source object.
{
"relevant_questions": [
{
"query": "What is the trend of sales by type over time?",
"data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca",
"data_source_name": "(Sample) Retail - Apparel"
},
{
"query": "Sales by item",
"data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca",
"data_source_name": "(Sample) Retail - Apparel"
},
{
"query": "Sales across regions",
"data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca",
"data_source_name": "(Sample) Retail - Apparel"
}
]
}