Tellius
  • 🚩Getting Started
    • 👋Say Hello to Tellius
      • Glossary
      • Tellius 101
      • Navigating around Tellius
      • Guided tours for quick onboarding
    • ⚡Quick Start Guides
      • Search
      • Vizpads (Explore)
      • Insights (Discover)
    • ✅Best Practices
      • Search
      • Vizpads (Explore)
      • Insights (Discover)
      • Predict
      • Data
    • ⬇️Initial Setup
      • Tellius architecture
      • System requirements
      • Installation steps for Tellius
      • Customizing Tellius
    • Universal Search
    • 🏠Tellius Home Page
  • Kaiya
    • ♟️Understanding AI Agents & Agentic Flows
      • Glossary
      • Composer
      • 🗝️Triggering an agentic workflow
      • The art of possible
      • Setting up LLM for Kaiya
    • 🤹Kaiya conversational AI
      • ❓FAQs on Kaiya Conversations
      • Triggering Insights with "Why" questions
      • Mastering Kaiya conversational AI
  • 🔍Search
    • 👋Get familiar with our Search interface
    • 🤔Understanding Tellius Search
    • 📍Search Guide
    • 🚀Executing a search query
      • Selecting a Business View
      • Typing a search query
      • Constructing effective search queries
      • Marketshare queries
    • 🔑Analyzing search results
      • Understanding search results
      • Search Inspector
      • Time taken to execute a query
      • Interacting with the resulting chart
    • 📊Know your charts in Tellius
      • Understanding Tellius charts
      • Variations of a chart type
      • Building charts from Configuration pane
      • List of chart-specific fields
      • Adding columns to fields in Configuration pane
      • Absolute and percentage change aggregations
      • Requirements of charts
      • Switching to another chart
      • Formatting charts
      • Advanced Analytics
      • Cumulative line chart
    • 🧑‍🏫Help Tellius learn
    • 🕵️‍♂️Search history
    • 🎙️Voice-driven search
    • 🔴Live Query mode
  • 📈Vizpads (Explore)
    • 🙋Meet Vizpads!
    • 👋Get familiar with our Vizpads
    • #️⃣Measures, dimensions, date columns
    • ✨Creating Vizpads
    • 🌐Applying global filters
      • Filters in multi-BV Vizpads
      • Filters using common columns
    • 📌Applying local filters
    • 📅Date picker in filters
      • Customizing the calendar view
    • ✅Control filters
      • Multi-select list
      • Single-select list
      • Range slider
      • Dropdown list
    • 👁️Actions in View mode
      • Interacting with the charts
    • 📝Actions in Edit mode
      • 🗨️Viz-level actions
    • 🔧Anomaly management for line charts
      • Instance level
      • Vizpad level
      • Chart level
    • ⏳Time taken to load a chart
      • Instance level
      • Vizpad level
      • Chart level
    • ♟️Working with sample datasets
    • 🔁Swapping Business View of charts
      • Swapping only the current Vizpad
      • Swapping multiple objects
      • Configuring the time of swap
    • 🤖Explainable AI charts
  • 💡Insights (Discover)
    • 👋Get familiar with our Insights
    • ❓Understanding the types of Insights
    • 🕵️‍♂️Discovery Insights
    • ➕How to create new Insights
      • 🔛Creating Discovery Insight
      • 🔑Creating Key Driver Insights
      • 〰️Creating Trend Insights
      • 👯Creating Comparison Insights
    • 🧮The art of selecting columns for Insights
      • ➡️How to include/exclude columns?
  • 🔢Data
    • 👋Get familiar with our Data module
    • 🥂Connect
    • 🪹Create new datasource
      • Connecting to Oracle database
      • Connecting to MySQL database
      • Connecting to MS SQL database
      • Connecting to Postgres SQL database
      • Connecting to Teradata
      • Connecting to Redshift
      • Connecting to Hive
      • Connecting to Azure Blob Storage
      • Connecting to Spark SQL
      • Connecting to generic JDBC
      • Connecting to Salesforce
      • Connecting to Google cloud SQL
        • Connecting to a PostgreSQL cloud SQL instance
        • Connecting to an MSSQL cloud SQL instance
        • Connecting to a MySQL Cloud SQL Instance
      • Connecting to Amazon S3
      • Connecting to Google BigQuery
        • Steps to connect to a Google BigQuery database
      • Connecting to Snowflake
        • OAuth support for Snowflake
        • Integrating Snowflake with Azure AD via OAuth
        • Integrating Snowflake with Okta via OAuth
        • Azure PrivateLink
        • AWS PrivateLink
        • Best practices
      • Connecting to Databricks
      • Connecting to Databricks Delta Lake
      • Connecting to an AlloyDB Cluster
      • Connecting to HDFS
      • Connecting to Looker SQL Interface
      • Loading Excel sheets
      • 🚧Understanding partitioning your data
    • ⏳Time-to-Live (TTL) and Caching
    • 🌷Refreshing a datasource
    • 🪺Managing your datasets
      • Swapping datasources
    • 🐣Preparing your datasets
      • 🤾Actions that can be done on a dataset
      • Data Pipeline
      • SQL code snippets
      • ✍️Writeback window
      • 🧩Editing Prepare → Data
      • Handling null or mismatched values
      • Metadata view
      • List of icons and their actions
        • Functions
        • SQL Transform
        • Python Transform
        • Standard Aggregation
        • Creating Hierarchies
      • Dataset Scripting
      • Fusioning your datasets
      • Scheduling refresh for datasets
    • 🐥Preparing your Business Views
      • 🌟Create a new Business View
      • Creating calculated columns
      • Creating dynamic parameters
      • Scheduling refresh for Business Views
      • Setting up custom calendars
    • Tellius Engine: Comparison of In-Memory vs. Live Mode
  • Feed
    • 📩What is a Feed in Tellius?
    • ❗Alerts on the detection of anomalies
    • 📥Viewing and deleting metrics
    • 🖲️Track a new metric
  • Assistant
    • 💁Introducing Tellius Assistant
    • 🎤Voice-based Assistant
    • 💬Interacting with Assistant
    • ↖️Selecting Business View
  • Embedding Tellius
    • What you should know before embedding
    • Embedding URL
      • 📊Embedding Vizpads
        • Apply and delete filters
        • Vizpad-related actionTypes
        • Edit, save, and share a Vizpad
        • Keep, remove, drill sections
        • Adding a Viz to a Vizpad
        • Row-level policy filters
      • 💡Embedding Insights
        • Creating and Viewing Insights
      • 🔎Embedding Search
        • Search query execution
      • Embedding Assistant
      • 🪄Embedding Kaiya
      • Embedding Feed
  • API
    • Insights APIs
    • Search APIs
    • Authentication API (Login API)
  • ✨What's New
    • Release 5.4
      • Patch 5.4.0.x
    • Release 5.3
      • Patch 5.3.1
      • Patch 5.3.2
      • Patch 5.3.3
    • Release 5.2
      • Patch 5.2.1
      • Patch 5.2.2
    • Release 5.1
      • Patch 5.1.1
      • Patch 5.1.2
      • Patch 5.1.3
    • Release 5.0
      • Patch 5.0.1
      • Patch 5.0.2
      • Patch 5.0.3
      • Patch 5.0.4
      • Patch 5.0.5
    • Release 4.3 (Fall 2023)
      • Patch 4.3.1
      • Patch 4.3.2
      • Patch 4.3.3
      • Patch 4.3.4
    • Release 4.2
      • Patch 4.2.1
      • Patch 4.2.2
      • Patch 4.2.3
      • Patch 4.2.4
      • Patch 4.2.5
      • Patch 4.2.6
      • Patch 4.2.7
    • Release 4.1
      • Patch 4.1.1
      • Patch 4.1.2
      • Patch 4.1.3
      • Patch 4.1.4
      • Patch 4.1.5
    • Release 4.0
Powered by GitBook

© 2025 Tellius

On this page
  • GET Insights
  • DELETE Insight
  • Other RESTful API
  • WebSocket notifications

Was this helpful?

Export as PDF
  1. API

Insights APIs

PreviousAPINextSearch APIs

Last updated 1 day ago

Was this helpful?

The following actions can be performed by using the relevant APIs. These actions do not require postMessage communication. So the steps outlined in 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",
this section