> For the complete documentation index, see [llms.txt](https://help.tellius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tellius.com/tellius-5.6/api/insights-apis.md). # Insights APIs Leverage Tellius Insights APIs to generate, retrieve, and embed AI-driven insights—automate analytics workflows with RESTful endpoints. 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-5.6/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 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.tellius.com/tellius-5.6/api/insights-apis.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.