Developer Zone

Quick-Start Guide

The Usage Intelligence API has been built from the ground up to be as flexible as possible. Every report available on the Usage Intelligence Web UI is also available through the API. It is best to start learning how to use the API by trying out simple queries, and then start working on more complex queries at a later stage.

Before building your first queries you should understand the following:

Authentication Method

Before generating a report you must first authenticate with the API server by using one of the 2 methods below:

  • Using user and session ID that are sent manually with every request
  • Using cookies

If the API is to be accessed via a browser, then the cookie method is normally the most convenient way how to manage the authentication session. If you are writing a script or an application that needs to authenticate automatically and retrieve data without involving web browsers, then it is normally easier to avoid having to use cookies and managing the user name and session ID within your script. For more details about authentication, visit the Authentication page.

HTTPS Method

Report queries may be sent either using POST or GET requests. Whenever possible, POST is the preferred option. When using POST requests, the request data is to be sent as the POST data. GET requests are to be used in cases where using POST is not possible such as when requesting data as an iframe source. In such cases, the request data is to be sent URL encoded as part of the URL inside a parameter named “query”. For more details about these 2 methods, visit the POST vs GET Requests page.

Raw vs Formatted Results

The results that the server returns can either be in a raw JSON format or else can be pre-formatted by the server as an HTML page that includes a chart or table which can be embedded in your page. The raw JSON format is meant to be read by scripts or applications and used for further processing. At the moment, the response can either be sent in raw JSON, or else as a Highcharts chart. Please note that if you choose to use Highcharts in your application, you may require a Highcharts license.

Example Request

In this very basic example, it is assumed that we are accessing the API from a web browser and we would like to get a timeline of the last 60 days showing the number of new, active, and lost users. Normally, the target URL should be used to set the target URL of an iframe, however, for testing, you may simply paste the URL in the browser address bar.

In this example, we are using cookie-based authenication. Since we are getting the data using GET requests, the API server will automatically redirect us to the login page if we are not already logged in. Therefore, we do not need to worry about authentication at this stage.

Building the JSON Request object

The following is the JSON object which we will be sending as the request. For this example, we will be requesting data from the demo product account.

    "productId": 2376158762,
    "startDate": "NOW-60",
    "stopDate": "NOW",
    "dateSplit": "day",
    "clientStatus": [
    "daysUntilDeclaredLost": 30,
    "dateReportedLost": "dateDeclaredLost"

Encoding the request and getting the data

The JSON object should be sent as part of the request URL in a parameter named “query”. In this case, the URL should be as follows:{"productId":2376158762,"startDate":"NOW-60","stopDate":"NOW","dateSplit":"day","clientStatus":["new","active","lost"],"daysUntilDeclaredLost":30,"dateReportedLost":"dateDeclaredLost"}&resultFormat=highcharts&hcType=line

The “query” value needs to be URL encoded. All modern browsers automatically apply URL encoded to unencoded paramter values. However, it is always recommended to apply encoding before sending the URL. In such case, the encoded URL would be as follows: