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:

Access Admin > System > API Toolkit
Get Search Results
- Example Response
- Fields Description
Configure Search History
1. Get Search History
  - Example Response
  - Fields Description
2. Add Items to Search History
Get Search Setup Info
- Example Response
- Fields Description

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:

Field Name	Value Type	Description
business_owner	string	The name of the Element Business Owner.
business_owner_id	string	The ID of the Element Business Owner.
category_name	string	The name of the element's category.
certification_level_id	string	The ID of the certification level.
certified_ind	string	Whether or not the element is certified. Takes value “Y” if the element is certified, “N” - if not.
custom_fields	array	An array of the element's Custom Fields.
description	string	The element's description.
description_markdown_ind	string	Whether or not markdown is applied to the element's description. Takes value “Y” if markdown is enabled, “N” - if not.
edit_allowed	string	Whether or not the element can be edited by the user executing API call.
element_id	string	The ID of the element.
external_content_type_name	string	If the element is an External Content, describes its type.
external_report_display	string	If the element is an External Report, describes its display options.
external_report_reference_id	string	The original ID of the External Report in the BI tool.
last_certified_by_name	string	The name of the user who certified the element.
last_certified_time	string	The date and time of the last certification of the element.
metric_tile_display_pct_variance	string	The percentage ratio between the two latest metric values.
name	string	The name of the element.
plugin_connection_profile_id	string	The ID of the element's Plugin Connection Profile.
reporting_tool_name	string	If the element is an External Report, displays the name of the BI tool from which the element is populated.
segment_value_id	string	The dimension value of the element.
tags	array	An array of the element's tags and glossary terms.
technical_owner	string	The element's Technical Owner.
technical_owner_id	string	The ID of the element's Technical Owner.
total_view_count	string	The engagement count of the element.
type	string	The type of the element.
user_dashboard_element_instance_id	string	A unique ID of the element record.

Dataset:

Field Name	Value Type	Description
can_be_used_as_access_map_ind	string	Whether or not the Dataset can be used as an Access Map (User Map). Takes value “Y” if the Dataset can be used as an Access Map, “N” - if not.
category_name	string	The name of the Dataset category.
certified_ind	string	Whether or not the element is certified. Takes value “Y” if the element is certified, “N” - if not.
columns	string	Dataset's column names separated by the delimiter #$%@#$%^$#*.
custom_fields	array	An array of the Dataset's Custom Fields.
dataset_id	int	The ID of the Dataset.
description	string	The description of the Dataset.
edit_allowed	string	Whether or not the element can be edited by the user executing API call.
last_certified_by_name	string	The name of the user who certified the element.
last_certified_time	string	The date and time of the last certification of the Dataset.
name	string	The name of the Dataset.
tags	array	An array of the element's tags and glossary terms.
type	string	The type of the element.

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

Field Name	Value Type	Description
type	string	The type of the returned search entity.
item_id	integer	The ID of the search entity.
second_id	string	The segment value of the element.
title	array	The title of the Dataset data entity.
external_link	string	The external link of the Dataset data entity.
clicked_time	string	The last time the element has been clicked.
clicked_count	integer	The number of times the element has been clicked.

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.

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"
  }
}

Fields Description

Field Name	Value Type	Description
llm_model	string	The main large language model (LLM).
context_llm_model	string	Optional Large Context LLM for large content processing (required for Azure).
llm_deployment_name	string	LLM version identifier.
llm_api_type	string	LLM API provider. The supported values are azure and openai.
llm_api_base	string	LLM API endpoint URL (required for Azure)
llm_api_version	string	LLM API version (required for Azure).

Search API

1. Access Admin > System > API Toolkit

2. Get Search Results

Example Response

Fields Description

3. Configure Search History

3.1. Get Search History

Example Response

Fields Description

3.2. Add Items to Search History

Element

Dataset

Dataset Data

4. Get Search Setup Info

Example Response

Fields Description

Topics

Last Updated

Other Resources