Skip to main content
You are viewing the documentation for Interana version 2. For documentation on the most recent version of Interana, go to


Scuba Docs

Query API implementation guide

Sachin Holla

Interana provides a set of RESTful APIs as part of the External API. These APIs are language/platform agnostic.

The purpose of this article is to specifically assist in creating a language-specific implementation that can be used for your custom scenario. After completing this how-to, you will have ready-to-run code capable of querying Interana using the supported Interana APIs.


Cluster URL

Assuming you have an Interana environment available, ensure that you can access the environment and can run queries using the UI. If you don't know the URL or don't have an environment, contact Interana Support (for Production environments) or your friendly Interana Solution Architect (for POC environments).

Interana dataset name

Access your Interana Environment and find the table or dataset to use for your queries.

Authorization token

You must have an authorization token to access the Interana API. This will allow you to access the API and pass the authentication step.

Contact Interana Support

This is the recommended path. This will be as simple as sending a quick email to Interana Support to request a token. Keep this token safe, since it can't be generated again.

Alternatively, see Generate an API token for information about creating your own API tokens. 

Install the Python SDK

The Python SDK is available on PyPI as a direct download. For further details, pl. see the SDK sources.

pip install interanasdk

Installing this package provides a python SDK for easy access to the Interana Query APIs documented here. In addition, there is a utility (ia_query_client) installed to allow for shell-level access to the APIs.

Note: This is a community supported SDK and we're providing it on a best-effort basis only. Interana will not provide support for this SDK.

Implementation: Python

This section describes how to create an implementation in Python.

We will use the Query SDK to assist in querying via Python. There are four main actions involved when attempting to query Interana using this SDK:

  • Create an Interana client object
  • Generate an Interana query object
  • Tune the query, if needed
  • Retrieve the results from Interana

Create an Interana client object

To get started, we will create an Interana client object. The purpose behind this step is to establish a connection to the Interana cluster that you will be querying from. To do this, start simply by specifying cluster host and the authorization token (from above). For eg:

from interanasdk import Client
url = "<cluster domain here without no http(s) or slashes>"
token = "<your authorization token>"
client = Client(url, token)

Generate an Interana query object

Next, initialize a query object using the SDK. This step helps define and formulate the query to retrieve the data. The information needed will be the dataset to query against (from above) and the date range (assuming the querying is from X days back to now). Assumption will be a base query type (number visualization in Interana) and base aggregator type ("count *"). 

import datetime
from interanasdk import Query
dataset = "<your dataset name>"
days_prior = 7
end_time =
start_time = end_time - datetime.timedelta(days=days_prior)
query = Query(dataset, start_time, end_time)
query_type = "single_measurement"
agg_type = "count_star"
ia_col = ""

Tune the query

Now you can filter the query object or issue group-by requests or change the query type. This step is not mandatory but can be used to further filter the query. Or do a group by to visualize the data differently. See the External API reference for more information about the parameters.

filter = "(`event` != \"userlogin\")"
query.add_query_info(type=query_type, aggregator=agg_type, column=ia_col, filter=filter_expr)
groupby_col = "event"

Retrieve results from Interana

Issue the request to the Interana backend to retrieve the result set for your query. This is the final step to actually get the dataset for the query defined.

result = client.query(query)
print result

Putting it all together: sample code

The complete code will look similar to the following:

#!/usr/bin/env python

import datetime
from interanasdk import Client, Query, InteranaError

url = ""
token = "Kl72RslnaXniep82kxgTbnlR5D77qPqchpPIUtuKcxpx21gbdheXd9mikfUh1pFyx1bUOK67V+S8Q19c0fgYPlJ7arrD0000"
client = Client(url, token)

dataset = "music"
days_prior = 7
end_time =
start_time = end_time - datetime.timedelta(days=days_prior)
query = Query(dataset, start_time, end_time)

query_type = "single_measurement"
agg_type = "count_star"
ia_col = ""

        result = client.query(query)
        print result
except InteranaError as e:
        print "Interana Error Recieved:"
        print "Error Code: %s, Error Details: %s" % (e.code,e.error)

except Exception as ex:
        print "Exception Recieved:"
        print ex

Use the Interana SDK utility

Alternatively, as part of the install, use the helper script that leverages the SDK and provides an easy to use wrapper utility to access the Interana APIs directly. For more details on the implementation of the utility, look here.


$ ia_query_client -h
usage: ia_query_client [-h] [-d DAYS_PRIOR] [-t QUERY_TYPE] [-a AGGREGATOR]
                          [-c COLUMN_NAME] [-g GROUP_BY] [-f FILTERS]
                          [-o OUTPUT_FILE] [-v]
                          auth_token cluster_domain dataset