# Insights APIs 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](/tellius-6.3/embedding-tellius/embedding-url/embedding-insights.md) to connect with Tellius are not applicable here. The following APIs can be hit directly to achieve the required tasks. ### **GET Insights** ***Request URL:*** ***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:*** ```sql '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: \ -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:*** ***Request Method:*** DELETE ***CURL:*** ```rust curl -v -X DELETE \ -H "Content-Type: application/json" -H "Cache-Control: no-cache" \ -H 'Authorization: \  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: * **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: ```nginx curl -X PUT \ https://dev.app.tellius.com/insight/insightID \  -H 'authorization: ' \  -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 -- which can be used to get redirected to the required Insight. ```json { "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 -- which can be used to get redirected to the required Insight. ```json { "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", ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.tellius.com/tellius-6.3/api/insights-apis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.