Developer Zone

POST vs GET Requests

The Usage Intelligence API offers 2 request method options - HTTP POST or HTTP GET requests. These options are being offered for flexibility and to allow insertion of reports inside different applications which may range from desktop applications, scripts, browser-side Javascript, and even static HTML pages.

When to use GET

HTTP GET is the kind of request that is normally used to request a web page. This kind of request is not meant to send large amounts of data. The advantage of GET requests is that all data that is to be sent, is encoded within the URL itself. Therefore, the URL can be copied to other users, used as an iframe src, or saved as a browser bookmark.

When requesting formatted reports which are meant for immediate display rather than for further processing, GET is normally the best option. When using GET requests in order to include a report as part of a web page, one does not need to worry about how to do the request itself. The easiest way is to create an iframe and simply place the URL in the iframe src attribute.

All the examples within this documentation use POST requests. However, all requests other than POST /auth/login can be accessed via a GET request. To request a report via GET, the same URL should be called, and the JSON request object should be formatted in exactly the same way. However, instead of sending the JSON object as POST data, it should be sent URL encoded inside a parameter named query.

When to use POST

HTTP POST requests are designed to send data over the web. This is the type of request that is used after filling an HTML form or when uploading a file. The advantage of this type of request is that it can send large amounts of data while keeping the URL short and simple. However, if the URL is copied, all data is lost.

When requesting raw (JSON) reports, which are meant for further local processing, POST requests are the preferred request method. This is because it is the method that is designed for long data request, and is cleaner and easier to understand. Therefore, if you are building a desktop application or writing a script in which your code (and not a browser) will be handling the request mechanism, it is recommended to use POST whenever possible.

Request example

The following is an example request of a date range report with no global filters and 1 segmentation level showing only the number of active users using each different product language. In this example, we are assuming that cookie-based authentication is being used, and therefore, the user and sessionId properties are not being used. Also, we are requesting a HighCharts column chart by adding the following parameters to the URL: &resultFormat=highcharts&hcType=column

The following is the JSON object which is to be sent, regardless of whether this is a GET or POST request:

    "productId": 2376158762,
    "startDate": "NOW-60",
    "dateSplit": null,
    "clientStatus": [
    "levels": {
        "level1": {
            "property": "prodLanguage",
            "segments": [
                    "type": "regex",
                    "value": ".*"
                    "split": true

The following is how the request URL should look with URL encoding:*%22%2C%22split%22%3Atrue%7D%5D%7D%7D%7D&resultFormat=highcharts&hcType=column

To better understand the above example, the following is the same URL without using URL encoding:{"productId":2376158762,"startDate":"NOW-60","dateSplit":null,"clientStatus":["active"],"levels":{"level1":{"property":"prodLanguage","segments":[{"type":"regex","value":".*","split":true}]}}}&resultFormat=highcharts&hcType=column