Public API v1 → Insight Query Endpoint

About the /dashboards/{dashboardGuid}/insights/{insightGuid}/query endpoint

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. This endpoint is accessed with a POST request.

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

Note

You must use the HTTPS scheme to be able to successfully run the API endpoints.

Header requirements

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 v1 → Create Token Endpoint.

Following is an example of the authorization line required in the request header:

Authorization: "Bearer <Access Token>"

Endpoint URL

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

https://<cluster_URL>/incorta/api/v1/dashboards/<dashboardGuid>/insights/<insightGuid>/query

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>

Request body

The /dashboards/{dashboardGuid}/insights/{insightGuid}/query endpoint will accept an optional JSON payload that can be used to filter the response data. Following is an example request payload with descriptions of each field:

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

prompts: An optional array of objects to add prompts to your query.

  • field: A string value containing the absolute path of the table column (the fully qualified name of the column: schemaName.tableName.columnName) filtered by the prompt.

  • operator: A string value of the prompt’s operator; e.g. =, >, <.

  • values: An array of string values containing the filter values.

  • options: An object for specific features of prompt.

    • caseSensitive: A boolean value 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.
  • type: A string value prompt type. String value must be either “dimension” or “variable”.

  • variable: A string value of the prompt’s variable name.

pagination: An optional object to add pagination to your query.

  • startRow: An integer value of the starting row for pagination.

  • pageSize: An integer value of the number of rows per page.

username: An optional string value, encoded in base64, to have your query processed as another user.

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

Endpoint response

The /dashboards/{dashboardGuid}/insights/{insightGuid}/query endpoint has five possible response codes and payloads.

CodeDescriptionPayload Response
200OKSee Dashboard query: 200 Response
400Bad Request{"message": "string"}
404Not Found{"message": "string"}
422Unprocessable Entity{"message": "string"}
500Internal Server Error{"message": "string"}

Endpoint 200 response

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