Powered by Redocly

Usage Intelligence Reporting API (3.0.0)

Download OpenAPI specification:Download

The Usage Intelligence Reporting API is targeted for advanced users who would like to build their own dashboards or integrate Usage Intelligence reporting (charts or raw data) within third party applications. The API can also be used to export data and statistics out of the Usage Intelligence servers for archiving or custom processing by other solutions.

NOTE: For information on global filters and segmentation in API reporting, see Global Filters and Segmentation and Levels (Date-Range Reports).

For Developer: To access our APIs programmatically, begin by obtaining the CSRF cookie. Send a GET request to the /v3/request-csrf endpoint with the appropriate headers, as specified in the auth API. Upon success, you'll receive a 204 status code. Then, utilize this obtained cookie when while using the auth API. After successful authentication, you'll receive two cookies: RUI-Csrf and RUI-Session-Token. Keep these cookies for subsequent requests. If authentication fails, expect to receive a 401 error code.

NOTE: The value for Origin should be https://analytics.revenera.com for all API endpoints. Providing a different value will result in an error.

Auth

Authenticate

Before being able to request any data, one needs to authenticate with the API. If authentication is not done, further requests will be rejected and 401 error code will be returned.

NOTE: If you encounter “Cookie Missing” error, retry the request you should be able to authenticate.

Request
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
required
userName
string
password
string
Responses
200

OK

400

Bad Request

post/v3/auth/web
Request samples
application/json
{
  • "userName": "test@test.com",
  • "password": "helloTest"
}
Response samples
application/json
{
  • "account": {
    },
  • "freeware": {
    },
  • "products": {
    },
  • "userSettings": {
    },
  • "currentProductDetails": {
    },
  • "beatInterval": 302
}

Logout

In order to log out, it is required to invalidate the user session that was created when logging in. If cookies are being used, the cookie will also be invalidated. Two options for logging out are being offered - either invalidate a single session or else, invalidate all sessions that are active on your user ID.

Request
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
string
Responses
204

No Content

post/v3/auth/logout
Request samples
application/json
{ }

Metadata Queries

Getting a List of Filter / Segmentation Properties

This request is to be used to get a list of properties by which you can filter or segment your reports.

Request
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Responses
200

OK

404

Not Found

get/v3/meta/productProperties
Response samples
application/json
{
  • "result": [
    ]
}

Getting a List of Possible Property Values

This request is used in order to get a list of possible values for the selected property. This data is then used to build filters or segments as required.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
property
string
Responses
200

OK

422

Unprocessable Entity

post/v3/meta/propertyValues/{product_id}
Request samples
application/json
{
  • "property": "os",
  • "granularity": "edition"
}
Response samples
application/json
{
  • "result": [
    ]
}

Event Tracking Management

Listing Event Categories and Names

These requests are used to get a list of event names and categories that have been reported by your application to Usage Intelligence, know which ones have been enabled for collection, and also set which ones should be collected.

Request
path Parameters
product_id
required
string
query Parameters
flat
boolean
Example: flat=true
showEvents
string
Example: showEvents=all
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Responses
200

OK

422

Unprocessable Entity

get/v3/event-tracking/{product_id}
Response samples
application/json
{
  • "result": [
    ]
}

Generic Reports

Generic Date Range Reports

This reporting mechanism is to be used for generating reports regarding user activity within a particular specified date range. Depending on the request, this can create timeline charts, pie/bar charts, geographical maps, or hierarchical tables.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/generic/dateRange/{product_id}
Request samples
application/json
{
  • "clientStatus": [
    ],
  • "startDate": "2023-05-15",
  • "stopDate": "2023-07-13",
  • "groupBy": "clientId",
  • "daysUntilDeclaredLost": 40,
  • "dateReportedLost": "dateDeclaredLost",
  • "dateSplit": "week",
  • "globalFilters": {
    },
  • "resultMode": "absolute",
  • "levels": {
    }
}
Response samples
application/json
{
  • "result": {
    }
}

Generic Current Reports

This reporting mechanism is to be used for generating reports regarding the current status of your product user base. Depending on the request, this can create pie/bar charts, geographical maps, or hierarchical tables.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/generic/current/{product_id}
Request samples
application/json
{
  • "clientStatus": [
    ],
  • "startDate": "2023-05-15",
  • "daysUntilDeclaredLost": 40,
  • "dateReportedLost": "dateDeclaredLost",
  • "globalFilters": { },
  • "levels": {
    },
  • "groupBy": "clientId",
  • "resultMode": "percentOfActive"
}
Response samples
application/json
{
  • "result": {
    }
}

User Engagement Histogram

Usage Distribution Histogram

The User Distribution Histogram report consists of three histograms which show the following metrics:

  • Active Days—The number of days clients were active within the specified date range.
  • Sessions—The number of times users launched your application.
  • Runtime—The total amount of time in hours users spent interacting with your application.
Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/engagement/usageDistribution/{product_id}
Request samples
application/json
{
  • "globalFilters": { },
  • "startDate": "2022-01-01",
  • "stopDate": "2023-05-30"
}
Response samples
application/json
{
  • "result": {
    }
}

Event Tracking Reports

Lifetime Events Tracking Histogram

The aim of this report is to show how events occur throughout the clients' lifetime. The data is presented as a histogram showing only a subset of events as specified. The histogram shows how many clients performed an event throughout their lifetime or their average daily/weekly/monthly usage.

This report returns data that is to be represented in chart format. The result consists of histogram-style data for each different event or event combination that has been requested. The results consist of 4 histograms based on different values: event counts, average event count per day, average event count per week, and average event count per month.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/eventTracking/lifetime/histogram/{product_id}
Request samples
application/json
{
  • "startDate": "2023-05-15",
  • "stopDate": "2023-07-13",
  • "groupBy": "clientId",
  • "globalFilters": { },
  • "events": [
    ]
}
Response samples
application/json
{
  • "summary": {
    },
  • "result": {
    }
}

Lifetime Event Tracking Data Table

The aim of this reports is to show how events occur throughout the clients' lifetime. The data is presented as a paged table which shows a list of all events and how many times each occurred.

This report returns data that is to be represented in tabular format. It contains data about each tracked event, how many times it occurred, how many times each user performed each event on average, etc. The events can be presented either as a flat view or categorized hierarchically based on event category and name. Data for each event can then be segmented by any property.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/eventTracking/lifetime/dataTable/{product_id}
Request samples
application/json
{
  • "startDate": "2023-05-15",
  • "stopDate": "2023-07-13",
  • "globalFilters": { },
  • "events": null,
  • "sorting": {
    },
  • "categorizeEvents": true,
  • "paging": {
    },
  • "groupBy": "clientId",
  • "segmentBy": "prodEdition",
  • "segments": [
    ]
}
Response samples
application/json
{
  • "returnedEventsCount": 17,
  • "matchingEventsCount": 17,
  • "result": [
    ]
}

Event Usage Basic Data Table

This basic event tracking reports is presented in a data table format which is meant to show a list of all known events within a date range and how they occurred. This report contains data about each tracked event, how many times it occurred, how many times each user performed each event on average, etc.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/eventTracking/basic/dataTable/{product_id}
Request samples
application/json
{
  • "startDate": "2023-05-15",
  • "stopDate": "2023-07-13"
}
Response samples
application/json
{
  • "result": [
    ]
}

Event Usage Basic Timeline

This basic event tracking report is presented in a timeline format which is meant to show the daily usage of a small subset. Normally, the timeline chart is used to drill-down on a selection of events that can be seen on the data table. This report returns a daily/weekly/monthly timeline of how many times each of the requested events occurred. The event occurrence counts can optionally be divided by the number of users on each day/week/month, the number of user sessions, runtime hours, etc.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/eventTracking/basic/timeline/{product_id}
Request samples
application/json
{
  • "startDate": "2023-05-15",
  • "stopDate": "2023-07-13",
  • "dateSplit": "week",
  • "dataView": "usageCounts",
  • "divisor": null,
  • "events": [
    ]
}
Response samples
application/json
{
  • "result": {
    }
}

Advanced Events

This report provides a detailed view into how users are using your tracked events. It is available only for events selected for "advanced tracking" on the Event Tracking Management tab of the Product page. This report contains data about how many users used each event, many times each event occurred in total, how many times each user performed each event on average, etc. It also returns a histogram for each event showing the distribution of how many times each user performed each event.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/eventTracking/advanced/fullReport/{product_id}
Request samples
application/json
{
  • "startDate": "2022-01-01",
  • "stopDate": "2023-05-30",
  • "events": [
    ]
}
Response samples
application/json
{
  • "result": {
    }
}

License Key Registry Management

Retrieving and Searching License Keys From the Key Registry

This request is used in order to get a list of license keys known by the Usage Intelligence servers along with their details. This is also used to search the key registry for a particular key or set of keys either by the key value itself or by another property such as by the expiry date or the assigned license type.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/license-key-registry/{product_id}
Request samples
application/json
{
  • "filters": { },
  • "sorting": {
    },
  • "paging": {
    }
}
Response samples
application/json
{
  • "matchingKeysCount": 21,
  • "returnedKeysCount": 10,
  • "results": [
    ]
}

Updating New Keys in the Key Registry

This request is used in order to update existing keys in the key registry. Keys can be updated one by one or in batch. A single batch can contain both new and existing keys to be inserted or updated accordingly.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

Successful response

patch/v3/license-key-registry/update/{product_id}
Request samples
application/json
{
  • "licenseKey": "2c5bc269-ac2c-465c-8f07-25fa4930ce13",
  • "licenseType": "purchased",
  • "licenseStatus": {
    },
  • "installQuota": 2,
  • "notes": "test"
}

Inserting New Keys in the Key Registry Copy

This request is used in order to insert new keys into the key registry. Keys can be updated one by one or in batch. A single batch can contain both new and existing keys to be inserted or updated accordingly.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/license-key-registry/update/{product_id}
Request samples
application/json
{
  • "licenseType": "purchased",
  • "licenseStatus": {
    },
  • "installQuota": 2,
  • "notes": "test"
}

Custom Event Tracking

Latest Data Preview

This request returns the last few custom events that have been collected including the product and system metadata of the client on which each event was collected in JSON format.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/customEventTracking/getLastLines/{product_id}
Request samples
application/json
{
  • "lineCount": 2
}
Response samples
application/json
{
  • "fieldNames": {
    },
  • "result": [
    ]
}

Downloadable File Listing

This request returns the list of zipped CSV files containing custom event tracking data that are on the server. This list is to be used to see what files are available for download and then be able to request files for downloading.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Responses
200

OK

get/v3/customEventTracking/listFiles/{product_id}
Response samples
application/json
{
  • "openDailyFiles": [ ],
  • "dailyFiles": [
    ],
  • "monthlyFiles": [ ]
}

Download Zipped CSV

In order to download the data files containing custom event tracking data, the file needs to be requested to the API which returns a secure URL from which the file can be downloaded. The request and response are both JSON objects.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/customEventTracking/getDownloadUrl/{product_id}
Request samples
application/json
{
  • "fileName": "2376158762_cust_2023-07-11.zip"
}
Response samples

Exception Tracking

Latest Data Preview

This Latest Data Preview request returns the last few exceptions that have been collected including the product and system metadata of the client on which each exception was collected in JSON format.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/exceptionTracking/getLastLines/{product_id}
Request samples
application/json
{
  • "lineCount": 2
}
Response samples
application/json
{
  • "fieldNames": {
    },
  • "result": [
    ]
}

List Files Exceptions

This List Files Exceptions request returns the list of zipped CSV files that are on the server. This list is to be used to see what files are available for download and then be able to request files for downloading.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Responses
200

OK

get/v3/exceptionTracking/listFiles/{product_id}
Response samples
application/json
{
  • "openDailyFiles": [ ],
  • "dailyFiles": [
    ],
  • "monthlyFiles": [ ]
}

Download Zipped CSV

In order to download the exception tracking data files, the file needs to be requested to the API which returns a secure URL from which the file can be downloaded. The request and response are both JSON objects.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/exceptionTracking/getDownloadUrl/{product_id}
Request samples
application/json
{
  • "fileName": "2376158762_exc_2023-07-11.zip"
}
Response samples

Client Profile Report

Client Property List

The aim of this report is to retrieve a subset or all of the data about a client or a set of clients.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
object
Responses
200

OK

post/v3/reporting/clientPropertyList/{product_id}
Request samples
application/json
{
  • "retDailyData": {
    },
  • "properties": [
    ]
}
Response samples
application/json
{
  • "result": [
    ],
  • "nextClientId": "6EE7BA394847D19",
  • "reachedEnd": false
}

Client Property List Export

The aim of this request is to export all data about all clients by paging through all the data and storing the returned data for offline processing.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: */*
string
Responses
200

Successful response

post/v3/export/request/clientPropertyList/{product_id}

Raw Data Exports

List Files

This request returns the list of raw data export zipped files that are on the server. This list is to be used to see what files are available for download and then be able to request files for downloading. Raw Data Export functionality needs to be enabled on your product account for this functionality to work.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Responses
200

OK

get/v3/rawEvents/download/listFiles/{product_id}
Response samples
application/json
{
  • "fileList": [
    ]
}

Get Download URL

In order to download raw data export data files, the file needs to be requested to the API which returns a secure URL from which the file can be downloaded. The request and response are both JSON objects. Raw Data Export functionality needs to be enabled on your product account for this functionality to work.

Request
path Parameters
product_id
required
string
header Parameters
Content-Type
string
Example: application/json
RUI-Client
string
Example: Postman
RUI-Client-Version
string
Example: 0.0.1
Origin
string
Example: https://analytics.revenera.com
Request Body schema: application/json
fileName
string
Responses
200

OK

post/v3/rawEvents/download/getDownloadUrl/{product_id}
Request samples
application/json
{
  • "fileName": "2376158762_2023-07-12.zip"
}
Response samples