Historical Usage Data

Overview

The Historical Usage Data tool in the CSI Customer Center provides comprehensive analytics for your cloud-based licensing usage history. This tool allows you to view detailed historical usage patterns and analyze license utilization across different products and time periods. Cloud Historical Usage Data can be found in the CSI Customer Center under Cloud Licensing Tools > Historical Usage Data.

Required Permissions

To view the Cloud License Usage History in the CSI Customer Center, a user must be assigned a user role with the “Cloud License Historical Use Data” permission. This permission is enabled by default on all Template roles. Access to the External / API Access tab requires the Customer Account Administrator role.

Cloud Sign-In Tab

This tab shows historical usage data for Cloud Sign-in licenses only, displaying information for the number of licenses used, number of failures to obtain a license and users' usage data.

Graphical Data

Charts show license usage patterns over time and provide a detailed breakdown by signed-in user and machine. Charts can be filtered by product, product level and time period.

Features of the [Product] Licenses Used table:

Displays how many licenses were used each day
Hover over each blue bar to see a breakdown of how many signed-in users and machines used those licenses that day.
Displays the number of times a user failed to obtain a license that day
- Failure data can be drilled down to give specific user information and when they failed to obtain a license

Features of the [Product] User Usage Data table:

Displays software usage, in hours, for each signed-in user for each product level (if applicable)
Hover on the levels in the legend to highlight the usage for that specific level only

Data Export

The following data can be exported using the buttons, and corresponding dropdown, at the top right of the screen. Data can be exported for the specified product displayed in the graph or for all products owned.

User usage data exported:

Signed-in user name and email
Machine Name
Asset ID
Product name, version, level and edition
Start and end time of running the product
Duration the product was used (in minutes)
Customer account of the license

Data exported for failure to obtain license:

Date and timestamp of when license tried to be obtained
Signed-in user name and email
Machine Name
Product name and version
Customer account of user

[Product] Licenses Used table

[Product] User Usage Data table

Cloud Key Tab

This tab shows historical usage data for Cloud Key licenses only, displaying information for the number of licenses used and the number of failures to obtain a license.

Graphical Data

Charts show license usage patterns over time and provide a detailed breakdown by the user and machine (if obtained). Charts can be filtered by product, product level and time period.

Features of the [Product] Licenses Used table:

Displays how many licenses were used each day
Hover over each blue bar to see a breakdown of the users and machines who used those licenses that day.
Displays the number of users who failed to obtain a license that day
- Failure data can be drilled down to give specifics of when a user failed to obtain a license

Data Export

The following data can be exported using the buttons, and corresponding dropdown, at the top right of the screen. Data can be exported for the specified product displayed in the graph or for all products owned.

License usage data exported:

Date and timestamp
Event type (license obtained, license refreshed, license returned)
User first and last name (if obtained)
Computer name (if obtained)
Asset ID
Product name and level
Customer account of the license

Data exported for failure to obtain license:

Date and timestamp user tried to obtain license and failed
Product name
Customer account of the license

[Product] Licenses Used table

External / API Access Tab

External / API Access links allow users to programmatically access cloud sign-in license usage data, facilitating seamless integration with external systems, reporting tools, or custom applications. Please note this is only available for cloud sign-in license data.

Features:

Filter Selection: Choose from various filters, including Product, Level, and Period.
Real-Time URL Generation: Watch as the generated API URLs update in real-time based on your filter selections.
Easy Copying: Utilize the copy button next to each endpoint to quickly copy the generated URLs.
Endpoint Testing: Test endpoints directly in your browser or API client for immediate verification.

Auto-generated API URLs on External / API Access Tab

Getting Started

Upon first time, user may need to generate an access token using the Generate New Token button on the External / API Access Tab. From there, the API URLs will generate automatically and then be displayed.

Get started - an access token may need to be generated before the API URLs are generated

Available API Endpoints

1. getCloudSignInSuccessData - Example of response showing license obtained data format

Purpose: Retrieve successful cloud sign-in events with user and machine details
URL Format:

?mode=getCloudSignInSuccessData&accessToken=YOUR_ACCESS_TOKEN&customer=12345&entity=12345&m=waad|user_identifier&period=3&product=1&level=All

Response Example:

{
  "success": true,
  "data": [
    {
      "date": "sep-13-2025",
      "successCount": 15,
      "description": "15 licenses used on sep-13-2025",
      "eventType": "Get License"
    }
  ],
  "metadata": {
    "recordCount": 1,
    "generatedAt": "2025-10-13T18:17:37.442Z",
    "timezone": "America/Los_Angeles",
    "customerId": "71011",
    "entityId": "17422",
    "productId": "3",
    "productName": "ETABS",
    "level": "All",
    "period": "1",
    "startDate": "2025-09-13",
    "endDate": "2025-10-13",
    "dataType": "success",
    "isComplete": true
  }
}

2. getCloudSignInFailureData - Example of response showing failure data format

Purpose: Retrieve failed cloud sign-in events with failure details
Note: Failure data is not level-specific and shows all failures regardless of the level filter.

Response Example:

{
  "success": true,
  "data": [
    {
      "date": "sep-15-2025",
      "failureCount": 3,
      "description": "3 license failures on sep-15-2025",
      "eventType": "Failure"
    }
  ],
  "metadata": {
    "recordCount": 1,
    "generatedAt": "2025-10-13T18:20:15.887Z",
    "timezone": "America/Los_Angeles",
    "customerId": "71011",
    "entityId": "17422",
    "productId": "3",
    "productName": "ETABS",
    "level": "All",
    "period": "1",
    "startDate": "2025-09-13",
    "endDate": "2025-10-13",
    "dataType": "failure",
    "isComplete": true
  }
}

3. getCloudSignInUserUsageData - Example of user usage data response

Purpose: Get detailed user usage analytics with duration breakdowns by level

Response Example:

{
  "success": true,
  "data": [
    {
      "contactKey": "John Doe_john.doe@example.com",
      "contactName": "John Doe",
      "emailAddress": "john.doe@example.com",
      "totalDuration": 15.5,
      "levels": [
        {
          "levelName": "Advanced",
          "durationHours": 10.2
        },
        {
          "levelName": "Ultimate",
          "durationHours": 5.3
        }
      ]
    }
  ],
  "metadata": {
    "recordCount": 1,
    "generatedAt": "2025-10-13T18:17:37.442Z",
    "timezone": "America/Los_Angeles",
    "customerId": "71011",
    "entityId": "17422",
    "productId": "3",
    "productName": "ETABS",
    "level": "All",
    "period": "1",
    "startDate": "2025-09-13",
    "endDate": "2025-10-13",
    "totalContacts": 1,
    "totalUsageHours": 15.5
  }
}

4. getContactMachineData - Example of contact-machine details response

Purpose: Get contact-machine relationship data with grouped contact information

Response Example:

{
  "success": true,
  "data": [
    {
      "date": "sep-15-2025",
      "contactCount": 3,
      "description": "3 contacts active on sep-15-2025",
      "contacts": [
        {
          "contactName": "John Doe",
          "machines": [
            "DESKTOP-ABC123",
            "LAPTOP-DEF456"
          ]
        },
        {
          "contactName": "Jane Smith",
          "machines": [
            "WORKSTATION-789"
          ]
        },
        {
          "contactName": "Bob Johnson",
          "machines": [
            "DESKTOP-XYZ001"
          ]
        }
      ]
    }
  ],
  "metadata": {
    "recordCount": 1,
    "generatedAt": "2025-10-13T18:17:37.442Z",
    "timezone": "America/Los_Angeles",
    "customerId": "71011",
    "entityId": "17422",
    "productId": "3",
    "productName": "ETABS",
    "level": "All",
    "period": "1",
    "startDate": "2025-09-13",
    "endDate": "2025-10-13",
    "dataType": "combined",
    "isComplete": true
  }
}

5. exportLoginUserUsageData - Example of export data response showing detailed session information

Purpose: Export detailed user usage data with complete session metadata
Additional Parameters: ignoreFilters: Set to "true" for "All Products" export mode (default: false)

Response Example:

{
  "success": true,
  "data": [
    {
      "id": "123456",
      "contactName": "John Doe",
      "emailAddress": "john.doe@example.com",
      "machineName": "DESKTOP-ABC123",
      "assetId": "78901",
      "productName": "ETABS",
      "version": "v21.3.0",
      "itemLevel": "Advanced",
      "edition": "Professional",
      "startTime": "9/15/2025 8:30 am",
      "endTime": "9/15/2025 10:45 am",
      "durationMinutes": 135
    }
  ],
  "metadata": {
    "recordCount": 1,
    "generatedAt": "2025-10-13T18:17:37.442Z",
    "timezone": "America/Los_Angeles",
    "customerId": "71011",
    "entityId": "17422",
    "productId": "3",
    "productName": "ETABS",
    "level": "All",
    "period": "1",
    "startDate": "2025-09-13",
    "endDate": "2025-10-13",
    "ignoreFilters": false
  }
}

6. exportCloudSignInFailure - Example of export failure event data response

Purpose: Export detailed failure event data with complete failure context
Additional Parameters: ignoreFilters: Set to "true" for "All Products" export mode (default: false)

Response Example:

{
  "success": true,
  "data": [
    {
      "date": "Sep 15, 2025",
      "time": "10:45:12",
      "contactName": "Bob Johnson",
      "emailAddress": "bob.johnson@example.com",
      "machineName": "WORKSTATION-001",
      "productName": "ETABS",
      "majorVersion": "v21",
      "customerName": "CUST123 Acme Corporation"
    }
  ],
  "metadata": {
    "recordCount": 1,
    "generatedAt": "2025-10-13T18:17:37.442Z",
    "timezone": "America/Los_Angeles",
    "customerId": "71011",
    "entityId": "17422",
    "productId": "3",
    "productName": "ETABS",
    "level": "All (Note: Failures are not level-specific)",
    "period": "1",
    "startDate": "2025-09-13",
    "endDate": "2025-10-13",
    "ignoreFilters": false
  }
}

Parameter Reference Table

All Available API Parameters:

Parameter	Required	Description	Default	Notes
`accessToken`	Yes	Must match a token in CSI access token system	-	Validated against customrecord_csi_access_token
`customer`	Yes	Customer internal ID	-	Restricts data to customer's records
`entity`	Yes	Entity internal ID (often same as customer)	-	Additional access control
`m`	Yes	Auth0 authentication identifier	-	Format: waad\|user_identifier
`product`	No	Product internal ID	1	1=SAP2000, 2=CSiBridge, 3=ETABS, etc.
`level`	No	Level filter	All	Product-specific levels
`period`	No	Time period in months (1, 3, 6, 12)	1	Always applied regardless of ignoreFilters
`ignoreFilters`	No	Enable "All Products" mode	false	Only for export endpoints

All Products Export Mode

Comparison showing standard vs. "All Products" export results
The ignoreFilters=true parameter will enable comprehensive data export:
Supported Endpoints:

exportLoginUserUsageData
exportCloudSignInFailure
Behavior:
When false: Standard filtering applies - data filtered by product, level, and period
When true: Product and level filters bypassed - returns data for all products and levels within the specified time period
Time: Period filtering is always respected, regardless of the ignoreFilters value
Example URLs:

# Standard Export (filtered)
?mode=exportLoginUserUsageData&accessToken=TOKEN&customer=12345&entity=12345&period=3&product=1&level=All&m=waad|user
# All Products Export (comprehensive)
?mode=exportLoginUserUsageData&accessToken=TOKEN&customer=12345&entity=12345&period=3&ignoreFilters=true&m=waad|user

Timezone

All dateTime in API responses use America/Los_Angeles timezone (PST/PDT, UTC-08:00/-07:00)
The timezone field in metadata explicitly states "America/Los_Angeles"
The generatedAt field uses ISO 8601 format (e.g., 2025-10-13T18:17:37.442Z)

Error Handling

Example of error response in the browser or API testing tool
All endpoints will return standardized error responses:

{
  "success": false,
  "error": "Error message describing what went wrong",
  "errorType": "authentication|validation|server|execution|database",
  "errorCode": "SPECIFIC_ERROR_CODE",
  "data": [],
  "metadata": {
    "recordCount": 0,
    "generatedAt": "2025-01-16T10:30:45.123Z",
    "timezone": "UTC",
    "customerId": "12345",
    "entityId": "12345",
    "productId": "1",
    "level": "All",
    "period": "1",
    "startDate": "2024-12-16",
    "endDate": "2025-01-16",
    "isComplete": false
  }
}