Public API v2 → Insight Query Endpoint

About

The /dashboards/{dashboardGuid}/insights/{insightGuid}/query endpoint will return the data from a specified insight on a dashboard. You can optionally include prompts in your request payload to filter your results. You may also request the result data based on a different specified user.

For information about how to get started with Public API v2, refer to References → Public API v2.

Note

You must use the HTTPS scheme to be able to successfully run the API endpoints. Additionally, you must specify the tenant name (case-sensitive) in the endpoint request URL starting with the 2023.7.0 release.

Dynamic Fields behavior

Starting with 2024.1.0, if the specified insight uses one or more dynamic fields as measure columns, the endpoint returns the default field per each dynamic field.

Request headers

In the request header, you will need to include your access token with a type of Bearer.

For information about how to create an access token, refer to Public API v2 → Create an API access token.

{
   "Content-Type": "application/json",
   "Accept": "application/json",
   "Authorization": "Bearer {access_token}"
}

Endpoint URL

Following is the URL to call the /dashboards/{dashboardGuid}/insights/{insightGuid}/query endpoint.

https://{cluster_URL}/incorta/api/v2/{tenantName}/dashboards/{dashboardGuid}/insights/{insightGuid}/query

URL parameters

Parameter	Type	Description	Required
tenantName	String	The tenant name (case-sensitive)	Required
dashboardGuid	String	The GUID of the dashboard	Required
insightGuid	String	The GUID of the insight	Required

The dashboardGuid and insightGuid are located in the URL of the desired dashboard insight. They are required in the /query endpoint URL. The following are instructions on where to locate the dashboardGuid and insightGuid:

As the user that wants to access the public API of a dashboard, sign into the Incorta Direct Data Platform™.
In the navigation bar, select Content.
Select the desired dashboard.
In the top right corner of the desired insight, select focus (expand arrows icon).
In your browser URL, locate the dashboardGuid and insightGuid in the URL.

Following is an example of where to locate the dashboardGuid and insightGuid in a dashboard URL:

https://{cluster_URL}/incorta/#/dashboard/{dashboardGuid}/tab/{tabGuid}/insight/{insightGuid}

HTTP method

POST

Endpoint URL example

https://mycluster.incorta.com/incorta/api/v2/default/dashboards/0va65534-b1cb-4xc7/insights/abc1234-gh78-33rf/query

Request body

The /dashboards/{dashboardGuid}/insights/{insightGuid}/query endpoint will accept an optional JSON payload that can be used to filter the response data.

{
  "prompts": [
    {
      "field": "string",
      "operator": "string",
      "values": [
        "string"
      ],
      "options": {
        "caseSensitive": true
      },
      "type": "string",
      "variable": "string"
    }
  ],
  "pagination": {
    "startRow": 0,
    "pageSize": 0
  },
  "username": "base64.encode(loginName)"
}

Request body parameters

The following table introduces the body parameters and their descriptions.

Parameter	Type	Description	Required
prompts	Array of objects	Prompts to filter the query	Optional
prompts > field	String	The absolute path of the table column (the fully qualified name of the column: `schemaName.tableName.columnName`) filtered by the prompt	Required
prompts > operator	String	The prompt’s operator. For example, =, >, <.	Required
prompts > values	Array of strings	The filter values	Required
prompts > options	Object	Specific features of the prompt	Optional
options > caseSensitive	Boolean	Specify if the prompt is case-sensitive. This option applies to the following operators only: `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH`, `NOT_STARTS_WITH`, and `ENDS_WITH`. For other operators, the value is always case-sensitive.	Optional
prompts > type	String	The prompt type. Valid values are: ● dimension (default): for dimension prompts ● variable: for presentation variables	Optional
prompts > variable	String	The variable name if the type is variable	Optional
pagination	Object	Specify pagination options	Optional
pagination > startRow	Integer	The starting row for pagination	Optional
pagination > pageSize	Integer	The number of rows per page	Optional
username	String	The user name encoded in base64 to have the query processed as this user	Optional

Important

Although the request body is optional, if you add prompts to your query, you must specify the field, operator, and value for each prompt. You must also include the type parameter.

Username field

The username optional field can only be used by a user with the Super User role. When you apply the username field, the query will be processed as if the request is from the specified user. The username in this field must be a different user than the user account associated with your API key. From your terminal, the following code example can be used to generate the base64 encoded username:

echo -n '<loginname>' | base64

Request body example

{
  "prompts": [{
      "field": "Online_Store.OrderDetails.ProductName",
      "operator": "CONTAINS",
      "values": ["Helmet"],
      "type": "dimension"}],
  "pagination": {
      "startRow": 1,
      "pageSize": 4}
}

Endpoint response

The following table shows the HTTP response status codes for this endpoint.

Code	Description	Payload Response
200	OK	See Endpoint 200 response
400	Bad Request	`{"message": "string"}`
401	Unauthorized ● Invalid or expired access token. ● The tenant name doesn’t match the tenant in the access token.	`{"message": "string"}`
404	Not Found ● The dashboard or insight doesn't exist. ● The tenant doesn't exist or is disabled.	`{"message": "string"}`
422	Unprocessable Entity	`{"message": "string"}`
500	Internal Server Error	`{"message": "string"}`

Endpoint 200 response

{
  "headers":{
    "dimensions": [
      {
        "columnName": "string",
        "dataType": "string",
        "label": "string",
        "type": "string",
        "index": 0
      }
    ],
    "measures": [      
      {
        "columnName": "string",
        "dataType": "string",
        "label": "string",
        "index": 0,        
        "grandTotal": "string"
      }
    ],
    "apiVersion": 0,
    "totalRows": 0
  },  
  "data": "string",
  "links": "string",
  "conditionalFormatting": "string"
}