Skip to main content
Interania

Programmatically query Interana with the API

The Interana external API lets you extract summarized and aggregated data for use in downstream processes, dashboards, or reports.

To use the API, you need an API token and a query identifier. Once you have these two pieces of information, you can submit GET or POST requests through the API.

API queries use cluster resources on a scale similar to ad hoc queries initiated in the Interana UI. To maintain performance across your Interana cluster when using the query API, use the same best practices for query efficiency that you use with queries that originate in the UI.

Generate an API token

You can generate an API token using your browser:

  1. In your browser, log into Interana.
  2. In the URL bar, append /api/create_token to the host name of your Interana cluster and hit Enter. For example, if your Interana host name is frob.interana.com, enter https://frob.interana.com/api/create_token.
  3. The browser immediately returns either a failure message or a success message with an API token. A success message looks like this:
    {"token": "san+aslnasw50293sjlfhgnoOvWW/sQH09y0", "success": true}
    the quoted string after "token" is the token (without the quotes). Copy (and paste) the token to use later.

Define a query

  1. Use the UI to define the query you wish to make programmatic. Press Go to run the query.
  2. When you press Go, the URL in your browser appends a query identifier, like r9372 or something similar. Copy the query identifier to use in the API later.

Use the API

Request

The API accepts HTTP GET and POST requests from any HTTP client.

Difference GET method POST method
Endpoint https://{your_domain_name}/v1/get_query http://{your_domain_name}/v1/query
Request parameter format Query string parameter JSON in the body of the request in the query_response_id field
Example request location .../get_query?query_response_id=r9372 {"query_response_id": "r9372"}

Your domain name is the URL at which you access the Interana UI. Pass the API token in the Authorization header prefixed with "Token" and separated by a single space.

Sample GET requests

You can optionally use the -X flag with curl to explicitly set the method:

$ curl -X GET https://11.2.34.141/v1/get_query?query_response_id=r9372 \
-H "Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0"

Pass the API token in the Authorization header prefixed with "Token" and separated by a single space.

You can optionally use the --verbose flag with curl and receive some output below the request, before the curl response:

$ curl 'https://11.2.34.141/v1/get_query?query_response_id=r9372' \
    -H 'Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0' --verbose
> GET /v1/get_query?query_response_id=r9372 HTTP/2
> Host: 11.2.34.141
> User-Agent: curl/7.54.0
> Accept: */*
> Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0

In an HTTP client, the GET request might look like the following:

GET /v1/get_query?query_response_id=r9372 \
HTTP/1.1 \
Host: 11.2.34.141 \
Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0
Sample POST requests

You can optionally use the --verbose flag with curl and receive some output below the request, before the curl response:

$ curl 'https://11.2.34.141/v1/query' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0' \
    -d '{"query_response_id": "r9372"}' --verbose
> POST /v1/query HTTP/2
> Host: 11.2.34.141
> User-Agent: curl/7.54.0
> Accept: */*
> Content-type: application/json
> Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0
> Content-Length: 32

Pass the API token in the Authorization header prefixed with "Token" and separated by a single space.

In an HTTP client, the POST request might look like the following:

POST /v1/query \
HTTP/1.1 \
Host: 11.2.34.141 \
Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0 \
Content-Type: application/json {"query_response_id": "r9372"}

Response

The response includes:

  • start and end times for every measurement
  • a measurement value for each measurement
  • a value for any split bys.

Here is a sample response for a simple show count of events query splitting by artist:

[
{
"measure 1":473,
"end_time_0":1540846400000,
"start_time_0":1540760000000
"artist": "All Others"
},
{
"measure 1": 130,
"end_time_0": 1540364400000,
"start_time_0": 1509260400000,
"artist": "Gorillaz"
},
{ "measure 1": 11,
"end_time_0": 154103400000,
"start_time_0": 15124300000,
"artist": "Beethoven"
},
...
]
  • Was this article helpful?