Insights APIs

se Tellius Insights APIs to generate, retrieve, and embed AI-driven insights with REST endpoints—automate analytics workflows and integrate insights into applications.

The following actions can be performed by using the relevant APIs. These actions do not require postMessage communication. So the steps outlined in this section to connect with Tellius are not applicable here. The following APIs can be hit directly to achieve the required tasks.

GET Insights

Request URL: https://dev.app.tellius.com/insight?includingShared=true&withSharings=true&limit=4&offset=0

Request Method: GET

• includingShared - returns the Viz object which is shared with the user

• limit - number of Insights to be returned

• offset - positions of the Insights to be returned. Say, for example, if there are 12 Insights in total, the limit=4 and offset=0, then the list of Insights starting from the very first Insight will be returned. For the same number of insights, if offset=4, then the list of Insights starting from the fourth Insight will be returned. Offset value starts from 0.

• onlyShared - If set to true, then only the Insights that are shared with (not created by) the user will be returned.

CURL:

'https://qa1.dev.tellius.com/insight?withSharings=true&limit=5&offset=4&includingShared=true' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Accept-Language: en-GB,en-US;q=0.9,en;q=0.8' \
  -H 'Authorization: <your_token_here> \
  -H 'Connection: keep-alive' \
  -H 'If-None-Match: W/"551b-J0tswd7gNWNihNncrhwgVfJIALU"' \
  -H 'Referer: https://qa1.dev.tellius.com/discover' \
  -H 'Sec-Fetch-Dest: empty' \
  -H 'Sec-Fetch-Mode: cors' \
  -H 'Sec-Fetch-Site: same-origin' \
  -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36' \
  -H 'sec-ch-ua: "Not?A_Brand";v="8", "Chromium";v="108", "Google Chrome";v="108"' \
  -H 'sec-ch-ua-mobile: ?0' \
  -H 'sec-ch-ua-platform: "macOS"' \
  --compressed

DELETE Insight

Request URL: https://dev.app.tellius.com/insight/insightID

Request Method: DELETE

CURL:

curl -v -X DELETE \
-H "Content-Type: application/json"
-H "Cache-Control: no-cache" \
-H 'Authorization: <your_token_here> \ 
http://52.87.228.68:8082/insight/myInsightId4  

Other RESTful API

GET the list of notifications

We can get the list of user notifications using the following API endpoint:

https://dev.app.tellius.com/api/jobs/list?createdBy=superUser&limit=10&type=Insight&includeConsumed=true&offset=0&sortBy=createdAt

• type - type of notification can be Insight, data, or ML

• createdBy - filters the notifications based on the creator

• limit - the notifications count

• includeConsumed - If set to true, then the notifications read will also be included.

• offset - the starting limit for pagination

Mark notifications as read

The following code can be used to mark the Insight notifications as read:

curl -X PUT \ https://dev.app.tellius.com/insight/insightID \  
-H 'authorization: <your_token_here>' \  
-H 'cache-control: no-cache' \  
-H 'content-type: application/json' \  
-H 'postman-token: b97aaee9-ac75-369e-2d75-026e4a7ef624' \  
-d '{ 
"consumed": true
}'

WebSocket notifications

If APIs are used directly to perform the required tasks on Insights, then one has to wait for the WebSocket notifications. These WebSocket notifications indicate whether a task is a success or a failure.

Notification on successful creation of an Insight

If an Insight is created successfully, the following response will be sent from WebSocket.

The code consists of both request and response information. The result section has components such as insightID and driverID. These two can be utilised to form the URL https://domain/discover/insight/insightID/driverID -- which can be used to get redirected to the required Insight.

{
    "request": { //. request object passed to create insight
        "driverName": "TestInsights", // owner of the insight 
        "label": "Buyer_Name",
        "options": { 
            "featureselection_featurenames": "Row_ID,Order_ID", // selected features from columns
            "featureselection_includefeaturenames": "true",
            "targetLabel": "Aaron Bergman", // Insight concentrated around these values
            "treeDepth": "large,small",
            "sample": "0.1",
            "createStage": "false"
        }, 
        "sourceid": "Business_View_ID",
        "createdBy": "18d60756-712e-4867-a301-430ba7f58880",
        "labelType": "categorical" // values are categorical / continuous
    }, 
    "timetaken": "26s",
    "result": { 
            "insightId": "insight_1e2a",
            "driverId": "driver_c9d9",
            "type": "DriverCreateResponse"
    }, 
    "consumed": true,
    "jobType": "SegmentDiscoveryInsight", // jobType among trend / cohort / segment discovery
    "status": "SUCCESS", 
    "jobId": "0096d8db-e1ad-41e9-a7c9-b9c8fa338e39", 
    "starttime": "2021-03-11T10:16:54.491Z",
    "createdBy": "superUser",
    "estimatedResourceSizeBytes": 2663691
}

Notification on failure of an Insight creation

If an Insight creation has failed, the following response will be sent from the WebSocket with the below Object.

The code consists of both request and response information. The result section has components such as insightID and driverID. These two can be utilised to form the URL https://domain/discover/insight/insightID/driverID -- which can be used to get redirected to the required Insight.

{
    "request": { 
        "driverName": "testsegment",
        "label": "Returned",
        "options": { 
                "featureselection_featurenames": "Sales,Order_ID”,
                "featureselection_includefeaturenames": "true",
                "targetLabel": "No",
                "treeDepth": "large,small",
                "sample": "0.1",
                "createStage": "false" 
        },
        "sourceid": "bv_2f76372e-3141-48b7-9e1f-a8320d25cdf9",
        "createdBy": "003f82b6-2ae7-459f-9cd1-e07baa3978eb",
        "labelType": "categorical",
        "timerange": { 
                "type": "today",
                "datecolumn": "Order_Date" 
        } 
    }, 
    "consumed": false,
    "reason": { 
            "type": "GenericError", // type of error
            "code": 1,
            "message": "Applying filter or timerange is returning 0 rows of data", // reason for the failure 
            "severity": "error" 
    },
    "jobType": "SegmentDiscoveryInsight",
    "status": "FAILURE",
    "jobId": "d9ad4c93-50f0-42fe-b6ca-2f3ff010e4b0",
    "starttime": "2021-03-11T11:20:20.475Z",