Search API
This article describes the following API endpoints: search, search_history, and search_setup.
Prerequisites:
- Set up API access
- Verify that you have API access and obtain a token via get_token call
Table of contents:
1. Access Admin > System > API Toolkit
2. Get Search Results
The API call to api/search
returns search results based on the provided parameters' values.
- Item: search
- Method: GET
- Filter search results using the following parameters:
- q: Enter the search query
- scope: Whether to show all elements or only the ones accessible to the user executing the API call
- category: The ID of the category the elements from which are returned
- content: Filtration by content type, e.g.: 'metric', 'dataset'
- type: Whether to return all search entities ('all') or only elements ('elements')
- content_type: If the searched element is External Content, enter the ID which corresponds to the External Content Type
- thumbnail: Whether or not to return only elements with thumbnail ('Y'/'N')
- Enter an API Token
- [Run request]
Example Response
External Report:
{
"description": "Science",
"description_markdown": "",
"description_markdown_ind": "N",
"type": "external report",
"category_id": 357,
"business_owner_id": 190,
"technical_owner_id": 190,
"report_single_unit_label": null,
"report_multiple_units_label": null,
"report_no_units_label": null,
"certified_ind": "N",
"certification_level_id": null,
"last_certified_time": null,
"metric_unit_of_measure": null,
"external_report_reference_id": 3996108,
"plugin_connection_profile_id": 351,
"created_time": "2024-07-17 12:45:08",
"category_name": "Autosync",
"editAllowed": "Y",
"external_report_display": "external",
"name": "Science (Version 2)",
"element_id": 147646,
"segment_value_id": 0,
"is_empty_instance_ind": "N",
"last_measurement_value_formatted": null,
"last_measurement_time_formatted": null,
"total_forecast_amount_formatted": null,
"metric_tile_display_pct_variance": null,
"business_owner": "Admin",
"technical_owner": "Admin",
"total_view_count": null,
"last_certified_by_name": null,
"reporting_tool_name": "Tableau",
"external_content_type_name": null,
"report_rows": null,
"tags": null,
"user_dashboard_element_instance_id": 962658,
"custom_fields": []
},
Dataset:
{
"dataset_id": 18341,
"name": "Smart Folder Dataset",
"description": "",
"certified_ind": "N",
"last_certified_time": "0000-00-00 00:00:00",
"category_name": "My Reports and Data",
"can_be_used_as_access_map_ind": "N",
"editAllowed": "Y",
"columns": "element_id#$%@#$%^$#*dim_value#$%@#$%^$#*views",
"last_certified_by_name": null,
"tags": null,
"custom_fields": [],
"type": "dataset"
},
Fields Description
NOTE: This description covers only the fields that contain information useful for Portal Page development, the fields that are not covered are for internal use only.
External Report:
Dataset:
3. Configure Search History
3.1. Get Search History
This API endpoint returns search entities that the user has clicked on.
- Item: search_history
- Method: GET
- Enter an API Token
- [Run request]
Example Response
{
"items": [
{
"type": "dataset_data",
"item_id": 549,
"second_id": 0,
"title": [
"Canada",
"549",
""
],
"external_link": "Canada",
"clicked_time": "2025-01-06 18:04:40",
"clicked_count": 1
},
{
"type": "dataset",
"item_id": 18313,
"second_id": 0,
"title": null,
"external_link": null,
"clicked_time": "2024-12-03 19:33:49",
"clicked_count": 1
},
{
"type": "element",
"item_id": 122889,
"second_id": 0,
"title": null,
"external_link": null,
"clicked_time": "2024-11-12 16:33:47",
"clicked_count": 2
},
{
"type": "element",
"item_id": 122249,
"second_id": 0,
"title": null,
"external_link": null,
"clicked_time": "2024-11-11 12:39:46",
"clicked_count": 2
}
]
}
Fields Description
3.2. Add Items to Search History
Element
$.ajax({
url: "/api/search-history",
type: "POST",
data: {
type: "element",
item_id: <Element ID>,
search_text: "<Search Text>",
second_id: <Segment Value ID>
}
});
Provide the following values:
-
<Element ID>
- The ID of the element, -
<Search Text>
- The text input used to search for the element, -
<Segment Value ID>
- The segment value of the element.-
NOTE: Set this value to
0
if the element does not have a segment value.
-
NOTE: Set this value to
Example:
$.ajax({
url: "/api/search-history",
type: "POST",
data: {
type: "element",
item_id: 1785,
search_text: "Sales 2024",
second_id: 0
}
});
Dataset
$.ajax({
url: "/api/search-history",
type: "POST",
data: {
type: "dataset",
item_id: <Dataset ID>,
search_text: "<Search Text>",
second_id: 0
}
});
Provide the following values:
-
<Dataset ID>
- The ID of the Dataset, -
<Search Text>
- The text input used to search for the Dataset.
Example:
$.ajax({
url: "/api/search-history",
type: "POST",
data: {
type: "dataset",
item_id: 19894,
search_text: "Sales 2024",
second_id: 0
}
});
Dataset Data
$.ajax({
url: "/api/search-history",
type: "POST",
data: {
type: "dataset_data",
item_id: <Dataset Data ID>,
search_text: "<Search Text>",
second_id: "<Dataset Data Title>",
external_link: "<External Link>"
}
});
Provide the following values:
-
<Dataset Data ID>
- The ID of the Dataset Data, -
<Search Text>
- The text input used to search for the Dataset Data, -
<Dataset Data Title>
- The value that consists of Dataset Data name and Dataset ID separated by the delimiter#$%@#$%^$#*
.- NOTE: See Get Search History for details.
-
<External Link>
- The external link that is opened when you click on the Dataset Data entity.
Example:
$.ajax({
url: "/api/search-history",
type: "POST",
data: {
type: "dataset_data",
item_id: 39,
search_text: "Sales in New York",
second_id: "New York#$%@#$%^$#*39",
external_link: "https://local.mi.com"
}
});
4. Get Search Setup Info
This API endpoint returns information on Search configuration also available on Admin > System > Search Setup > Concierge tab. See Configure Concierge Settings for details.
- Item: search_setup
- Method: GET
- Enter an API Token
- [Run request]
Example Response
{
"search_setup": {
"llm_model": "gpt-4",
"context_llm_model": "",
"llm_deployment_name": "GPT4-32k",
"llm_api_type": "azure",
"llm_api_base": "https://metricinsightsaiservice.openai.azure.com",
"llm_api_version": "2023-06-01-preview"
}
}