Query API reference

Single Measurement Queries

Single measurement queries are queries that return a single result set. An example of a single measurement query is a Table view query that extracts a site’s top users based on the count of user events. Only one table of results is returned for the given time range. 

Time series queries are queries that return a result set for every data point in the query’s time range. In Interana Explorer, time series queries are rendered using the Time view.

Endpoints

The API currently supports one endpoint: query. The query endpoint allows the user to make queries against Interana. The URL path to the query endpoint is:

https://<cluster hostname>/api/v1/query

The query endpoint must be accessed with the GET http method.

Authentication and authorization

All requests to the API must be over SSL (https protocol).

The API uses a token based authentication model. Tokens can be created or revoked by Interana support, or you can generate your own API tokens. Tokens must be passed in the Authorization header of each request to the API in the following format:

Authorization: Token <token>

Every user account is authorized to make requests to the API, as long as they use a valid request token.

Requests

Requests to the query endpoint must be sent with the GET http method. The required query parameter defines the query to be executed on Interana. It is a JSON object that is URL-encoded and passed as a parameter to the request. 

Responses

The API will return the http status code 200 for successful requests to the query endpoint, along with a JSON object containing the results of the query.

Examples: single measurement and time series

{ 
  “dataset”: “Music”,
  "start": 1461567600000,
  "end": 1461999600000,
  "timezone_offset": -25200000,
  "queries": [ {
    "type": "single_measurement",
    "measure": {
      "aggregator": "unique_count",
      "column": "userId"
    },
    "filter": "(`artist` != \"*null*\")"
  } ],
  "sampled": true,
  "group_by": ["artist"],
  "max_groups": 5,
  "compute_all_others": false
}

{ 
  "rows": [
    {"values": [ [ "3 Doors Down"], 31456] },
    {"values": [ [ "Justin Bieber"], 31336] },
    {"values": [ [ "OneRepublic"], 31772] },
    {"values": [ [ "Taylor Swift"], 30136] },
    {"values": [ [ "The White Stripes"], 27036] }
   ],
  "columns": [
    {"type": "array", "label": ["artist"] },
    {"type": "number", "label": "measure_value"}
   ]
}

{ 
  “dataset”: “Music”,
  "start": 1461913200000,
  "end": 1461956400000,
  "timezone_offset": -25200000,
  "queries": [ {
    "type": "time_series",
    "measure": {"aggregator": "count_star"},
  } ],
  "sampled": true,
}

{ 
  "rows": [
    {"values": [ [ "All"], [
      {“timestamp”: 1461913200000, “properties”: {“object_count”: 25243, "event_count": 25243},
       "value": 8414.333333333332},
      ...
      {"timestamp": 1461934800000, "properties": {"object_count": 20977, "event_count": 20977},
       "value": 6992.333333333333},
      ...
      {"timestamp": 1461956400000, "properties": {"object_count": 27581, "event_count": 27581},
       "value": 9193.666666666666}
      ...
      ...
     ] ],
     "properties": {"window": 43200000, "resolution": 21600000, "rate": "minute"}
  } ],
  "columns": [
    {"type": "array", "label": ["result"] },
    {"type": "time_series", "label": "measure_value"}
   ]
}

Errors and retry

The API returns appropriate HTTP status codes for error cases and JSON objects containing error information. 

{
  "error": "Invalid parameter",
  "message": "End time must be after start time",
}

{
  "error": "Request limit exceeded",
  "message": "The request limit of 1000 queries has been reached. This token can be used for requests on 2016-03-18 00:00:00"
}

Request limits and throttling

By default, tokens are authorized to make 1 query per second and 1000 requests per day. Once that limit has been exceeded, requests using that token will be rejected with HTTP error 429 until the next day. Contact Interana customer support to request a limit increase.

Versioning

This is version 1 of the External API, indicated by the string “v1” in the URL path. This API may be expanded in future releases.

See also

See the Query API implementation guide to learn how to create a language-specific implementation that can be used for your custom scenario.

See the Query API troubleshooting topic if you need help troubleshooting issues with API calls.