Search API

1. Access Admin > System > API Toolkit

The API call to api/search returns search results based on the provided parameters' values.

  1. Item: search
  2. Method: GET
  3. 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')
  4. Enter an API Token
  5. [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.

  1. Item: search_history
  2. Method: GET
  3. Enter an API Token
  4. [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 #$%@#$%^$#*.
  • <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.

  1. Item: search_setup
  2. Method: GET
  3. Enter an API Token
  4. [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).