# Usage Intelligence Reporting API 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. ## Explore the APIs Using Postman To help you get hands-on experience with our APIs, we have provided a Postman collection for download. This collection will allow you to seamlessly test and explore the API endpoints in a familiar environment. ***How to explore APIs using Postman:*** 1. **Download the Postman Collection**: Download 2. **Import into Postman**: Open your Postman app and import the collection. 3. **Authenticate**: Replace the "username" and "password" placeholders with your credentials (the same ones used in the Usage Intelligence Dashboard at [https://analytics.revenera.com](https://analytics.revenera.com)) in the /auth/web API endpoint body, then click **Send**. 4. **Personalize**: Replace the demo "product_id" in the API endpoints with your own "product_id" and modify the sample payload as per your product’s requirements. Start exploring the APIs! Version: 3.0.0 ## Servers ``` https://analytics-api.revenera.com ``` ## Download OpenAPI description [Usage Intelligence Reporting API](https://rui-api.redocly.app/_bundle/v3_api_redocly.yaml) ## Auth ### Authenticate - [POST /v3/auth/web](https://rui-api.redocly.app/v3_api_redocly/auth/paths/~1v3~1auth~1web/post.md): 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. ### Logout - [POST /v3/auth/logout](https://rui-api.redocly.app/v3_api_redocly/auth/paths/~1v3~1auth~1logout/post.md): 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. ## Metadata Queries ### Getting a List of Filter / Segmentation Properties - [GET /v3/meta/productProperties](https://rui-api.redocly.app/v3_api_redocly/metadata-queries/paths/~1v3~1meta~1productproperties/get.md): This request is to be used to get a list of properties by which you can filter or segment your reports. ### Getting a List of Possible Property Values - [POST /v3/meta/propertyValues/{product_id}](https://rui-api.redocly.app/v3_api_redocly/metadata-queries/paths/~1v3~1meta~1propertyvalues~1%7Bproduct_id%7D/post.md): 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. ## Event Tracking Management ### Listing Event Categories and Names - [GET /v3/event-tracking/{product_id}](https://rui-api.redocly.app/v3_api_redocly/event-tracking-management/paths/~1v3~1event-tracking~1%7Bproduct_id%7D/get.md): 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. ## Generic Reports ### Generic Date Range Reports - [POST /v3/reporting/generic/dateRange/{product_id}](https://rui-api.redocly.app/v3_api_redocly/generic-reports/paths/~1v3~1reporting~1generic~1daterange~1%7Bproduct_id%7D/post.md): 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. ### Generic Current Reports - [POST /v3/reporting/generic/current/{product_id}](https://rui-api.redocly.app/v3_api_redocly/generic-reports/paths/~1v3~1reporting~1generic~1current~1%7Bproduct_id%7D/post.md): 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. ## User Engagement Histogram ### Usage Distribution Histogram - [POST /v3/reporting/engagement/usageDistribution/{product_id}](https://rui-api.redocly.app/v3_api_redocly/user-engagement-histogram/paths/~1v3~1reporting~1engagement~1usagedistribution~1%7Bproduct_id%7D/post.md): 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. ## Event Tracking Reports ### Lifetime Events Tracking Histogram - [POST /v3/reporting/eventTracking/lifetime/histogram/{product_id}](https://rui-api.redocly.app/v3_api_redocly/event-tracking-reports/paths/~1v3~1reporting~1eventtracking~1lifetime~1histogram~1%7Bproduct_id%7D/post.md): 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. ### Lifetime Event Tracking Data Table - [POST /v3/reporting/eventTracking/lifetime/dataTable/{product_id}](https://rui-api.redocly.app/v3_api_redocly/event-tracking-reports/paths/~1v3~1reporting~1eventtracking~1lifetime~1datatable~1%7Bproduct_id%7D/post.md): 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. ### Event Usage Basic Data Table - [POST /v3/reporting/eventTracking/basic/dataTable/{product_id}](https://rui-api.redocly.app/v3_api_redocly/event-tracking-reports/paths/~1v3~1reporting~1eventtracking~1basic~1datatable~1%7Bproduct_id%7D/post.md): 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. ### Event Usage Basic Timeline - [POST /v3/reporting/eventTracking/basic/timeline/{product_id}](https://rui-api.redocly.app/v3_api_redocly/event-tracking-reports/paths/~1v3~1reporting~1eventtracking~1basic~1timeline~1%7Bproduct_id%7D/post.md): 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. ### Advanced Events - [POST /v3/reporting/eventTracking/advanced/fullReport/{product_id}](https://rui-api.redocly.app/v3_api_redocly/event-tracking-reports/paths/~1v3~1reporting~1eventtracking~1advanced~1fullreport~1%7Bproduct_id%7D/post.md): 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. ## Churn-Related Reports ### Churn and Engagement - [POST /v3/reporting/engagement/churnAndEngagement/{product_id}](https://rui-api.redocly.app/v3_api_redocly/churn-related-reports/paths/~1v3~1reporting~1engagement~1churnandengagement~1%7Bproduct_id%7D/post.md): This report provides insight on the lifetime of lost users. It is meant to report what happened during the whole lifetime of these installations rather than what happened during a defined date range. This report shows how new installations during the specified date range were engaged or lost during their lifetime. This report does not only show users who were reported lost, but instead, all users who installed during the specified date range are included. By viewing this report, one can then see how many users were still active/engaged after x days/weeks/months. ### Churn Days Histogram - [POST /v3/reporting/churn/histogram/days/{product_id}](https://rui-api.redocly.app/v3_api_redocly/churn-related-reports/paths/~1v3~1reporting~1churn~1histogram~1days~1%7Bproduct_id%7D/post.md): This report provides insight on the lifetime of lost users. It is meant to report what happened during the whole lifetime of these installations rather than what happened during a defined date range. This report consists of a histogram that shows the number of days clients were active within their lifetime. ### Churn Runtime Histogram - [POST /v3/reporting/churn/histogram/runtime/{product_id}](https://rui-api.redocly.app/v3_api_redocly/churn-related-reports/paths/~1v3~1reporting~1churn~1histogram~1runtime~1%7Bproduct_id%7D/post.md): This report provides insight on the lifetime of lost users. It is meant to report what happened during the whole lifetime of these installations rather than what happened during a defined date range. This report consists of a histogram that shows the total amount of time in hours users spent interacting with your application. ### Churn Sessions Histogram - [POST /v3/reporting/churn/histogram/sessions/{product_id}](https://rui-api.redocly.app/v3_api_redocly/churn-related-reports/paths/~1v3~1reporting~1churn~1histogram~1sessions~1%7Bproduct_id%7D/post.md): This report provides insight on the lifetime of lost users. It is meant to report what happened during the whole lifetime of these installations rather than what happened during a defined date range. This report consists of a histogram that shows the number of times users launched your application. ### Churn User Activity Data Table - [POST /v3/reporting/eventTracking/churn/lifetime/dataTable/{product_id}](https://rui-api.redocly.app/v3_api_redocly/churn-related-reports/paths/~1v3~1reporting~1eventtracking~1churn~1lifetime~1datatable~1%7Bproduct_id%7D/post.md): The aim of this report is to show how events occurred throughout the churned clients' lifetime before they were lost. The data is presented as a paged table which shows a list of all events and how many times each 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. 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. ### Churn User Activity Histogram - [POST /v3/reporting/eventTracking/churn/lifetime/histogram/{product_id}](https://rui-api.redocly.app/v3_api_redocly/churn-related-reports/paths/~1v3~1reporting~1eventtracking~1churn~1lifetime~1histogram~1%7Bproduct_id%7D/post.md): The aim of this report is to show how events occurred throughout the churned clients' lifetime before they were lost. The data is presented as a histogram showing only a subset of events as specified. The histogram shows how much churned clients performed an event throughout their lifetime or their average daily/weekly/monthly usage. The report 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. ## License Key Registry Management ### Retrieving and Searching License Keys From the Key Registry - [POST /v3/license-key-registry/{product_id}](https://rui-api.redocly.app/v3_api_redocly/license-key-registry-management/paths/~1v3~1license-key-registry~1%7Bproduct_id%7D/post.md): 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. ### Updating New Keys in the Key Registry - [PATCH /v3/license-key-registry/update/{product_id}](https://rui-api.redocly.app/v3_api_redocly/license-key-registry-management/paths/~1v3~1license-key-registry~1update~1%7Bproduct_id%7D/patch.md): 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. ### Inserting New Keys in the Key Registry Copy - [POST /v3/license-key-registry/update/{product_id}](https://rui-api.redocly.app/v3_api_redocly/license-key-registry-management/paths/~1v3~1license-key-registry~1update~1%7Bproduct_id%7D/post.md): 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. ## Custom Event Tracking ### Latest Data Preview - [POST /v3/customEventTracking/getLastLines/{product_id}](https://rui-api.redocly.app/v3_api_redocly/custom-event-tracking/paths/~1v3~1customeventtracking~1getlastlines~1%7Bproduct_id%7D/post.md): 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. ### Downloadable File Listing - [GET /v3/customEventTracking/listFiles/{product_id}](https://rui-api.redocly.app/v3_api_redocly/custom-event-tracking/paths/~1v3~1customeventtracking~1listfiles~1%7Bproduct_id%7D/get.md): 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. ### Download Zipped CSV - [POST /v3/customEventTracking/getDownloadUrl/{product_id}](https://rui-api.redocly.app/v3_api_redocly/custom-event-tracking/paths/~1v3~1customeventtracking~1getdownloadurl~1%7Bproduct_id%7D/post.md): 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. ## Exception Tracking ### Latest Data Preview - [POST /v3/exceptionTracking/getLastLines/{product_id}](https://rui-api.redocly.app/v3_api_redocly/exception-tracking/paths/~1v3~1exceptiontracking~1getlastlines~1%7Bproduct_id%7D/post.md): 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. ### List Files Exceptions - [GET /v3/exceptionTracking/listFiles/{product_id}](https://rui-api.redocly.app/v3_api_redocly/exception-tracking/paths/~1v3~1exceptiontracking~1listfiles~1%7Bproduct_id%7D/get.md): 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. ### Download Zipped CSV - [POST /v3/exceptionTracking/getDownloadUrl/{product_id}](https://rui-api.redocly.app/v3_api_redocly/exception-tracking/paths/~1v3~1exceptiontracking~1getdownloadurl~1%7Bproduct_id%7D/post.md): 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. ## Client Profile Report ### Client Property List - [POST /v3/reporting/clientPropertyList/{product_id}](https://rui-api.redocly.app/v3_api_redocly/client-profile-report/paths/~1v3~1reporting~1clientpropertylist~1%7Bproduct_id%7D/post.md): The aim of this report is to retrieve a subset or all of the data about a client or a set of clients. ### Client Property List Export - [POST /v3/export/request/clientPropertyList/{product_id}](https://rui-api.redocly.app/v3_api_redocly/client-profile-report/paths/~1v3~1export~1request~1clientpropertylist~1%7Bproduct_id%7D/post.md): 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. ## Raw Data Exports ### List Files - [GET /v3/rawEvents/download/listFiles/{product_id}](https://rui-api.redocly.app/v3_api_redocly/raw-data-exports/paths/~1v3~1rawevents~1download~1listfiles~1%7Bproduct_id%7D/get.md): 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. ### Get Download URL - [POST /v3/rawEvents/download/getDownloadUrl/{product_id}](https://rui-api.redocly.app/v3_api_redocly/raw-data-exports/paths/~1v3~1rawevents~1download~1getdownloadurl~1%7Bproduct_id%7D/post.md): 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.