Combine license assignment and metering usage data for a single software

For one software, returns counts and per-computer lists for every license × usage bucket (licensed/unlicensed/expired × using/unused/underutilized) over the last N days. Supports filtering by domain, branch office, custom group and OS platform. Per-bucket items carry only resourceID, resourceName and domainNetbiosName. lastNDays is optional and defaults to 90; if supplied it is clamped to 90 (InvSoftwareMeteringUsage retention).

Endpoints

get /dcapi/inventory/software/{softwareID}/license/usageInsights

Copy full URL

Request URL

https://{serverurl}/dcapi/inventory/software/{softwareID}/license/usageInsights

Scope

DesktopCentralCloud.Inventory.READCopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

AcceptstringMandatory

application/licenseUsageInsightsResponse.v1+jsonCopied!

- Path Parameters

softwareIDstringMandatory

Software identifier. Obtain from the response of the Get Installed Software List API.

- Query Parameters

lastNDaysstringOptional

Time window in days (1-90). Defaults to 90 when omitted; values above 90 are silently clamped to 90.

maxRunTimeSecondsstringOptional

Any installed computer with windowed runtime less than or equal to this value falls into the licensedUnderutilized bucket.

domainNetbiosNamestringOptional

Domain name to filter computers. Obtain from the response of the Get Computers List API.

branchOfficeIDstringOptional

Branch Office ID to filter computers. Obtain from the response of the Get Remote Office List API.

customGroupIDstringOptional

Custom group ID to filter computers. Obtain from the response of the Get Custom Group List API.

osPlatformstringOptional

Filter computers by OS platform. Allowed values: 1 - Windows, 2 - Mac

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request GET \
  --url https://appdomains/dcapi/inventory/software/{softwareID}/license/usageInsights \
  --header 'Accept: application/licenseUsageInsightsResponse.v1+json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) {

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://appdomains/dcapi/inventory/software/{softwareID}/license/usageInsights"))
        .header("Accept", "application/licenseUsageInsightsResponse.v1+json")
        .header("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("appdomains")

headers = {
    'Accept': "application/licenseUsageInsightsResponse.v1+json",
    'Authorization': "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52"
    }

conn.request("GET", "/dcapi/inventory/software/{softwareID}/license/usageInsights", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("Accept", "application/licenseUsageInsightsResponse.v1+json");

    response = invokeUrl
    [
        url: "https://appDomains/dcapi/inventory/software/{softwareID}/license/usageInsights"
        type: GET
        headers: headersMap
        connection: connection_name
    ]

    info response;

$headers=@{}
$headers.Add("Accept", "application/licenseUsageInsightsResponse.v1+json")
$headers.Add("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomains/dcapi/inventory/software/{softwareID}/license/usageInsights' -Method GET -Headers $headers

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Hide Sub-Attributes

windowJSON Object

Time window used for usage aggregation. Contains lastNDays (int) - number of days back from now (defaults to 90 when not supplied; clamped to 1-90 since InvSoftwareMeteringUsage retains 90 days)

Show Sub-Attributes

softwareIDlong

Echo of the path parameter

softwareNamestring

Display name from InvSW.DISPLAY_NAME

softwareVersionstring

Version from InvSW.SOFTWARE_VERSION

swTypestring

Software type label - COMMERCIAL, NON_COMMERCIAL or UNIDENTIFIED

meteringConfiguredboolean

True if at least one metering rule exists for this software

meteringRulesarray

Configured metering rules for this software. Each rule carries appDefinitionID, ruleName, fileName, osPlatform and status (boolean - true when the rule is enabled)

licenseJSON Object

License block - purchased (boolean), totalCopies, installedCopies, remainingCopies, compliantStatus (IN_COMPLIANCE/OVER_LICENSED/UNDER_LICENSED/NOT_AVAILABLE), isExpired (boolean) and nested license object (licenseID, licenseOwner, totalCopies, details[]). When no license is purchased, license is null

Show Sub-Attributes

countsJSON Object

Integer counts summarising the software's license and usage posture across managed computers, broken down into named buckets (totalInstalled, licensedInstalled, unlicensedInstalled, licensedUsing, licensedUnused, licensedUnderutilized, unlicensedUsing, licensedExpiredButUsing). Each bucket value is the number of computers matching that condition, mirroring the per-computer lists under the computers key.

400HTTP code

401HTTP code

404HTTP code

500HTTP code

Sample Response: HTTP 200

License × usage insights for a software

Copied!

  {
    "meteringConfigured": true,
    "license": {
      "license": {
        "totalCopies": 5,
        "details": [
          {
            "expiryDate": 0,
            "purchaseDate": 0,
            "noOfCopies": 5,
            "licenseName": "SampleLicense_001",
            "licenseDetailsID": 1
          }
        ],
        "licenseID": 1,
        "licenseOwner": "SampleOwner"
      },
      "purchased": true,
      "totalCopies": 5,
      "compliantStatus": "IN_COMPLIANCE",
      "remainingCopies": 2,
      "isExpired": false,
      "installedCopies": 3
    },
    "softwareID": 23,
    "softwareName": "Beyond Compare 5.2.0",
    "meteringRules": [
      {
        "fileName": "BCompare.exe",
        "appDefinitionID": 9001,
        "ruleName": "BeyondCompare-Win",
        "osPlatform": 1,
        "status": true
      }
    ],
    "counts": {
      "licensedExpiredButUsing": 0,
      "unlicensedInstalled": 0,
      "licensedUnused": 1,
      "unlicensedUsing": 0,
      "totalInstalled": 3,
      "licensedUnderutilized": 0,
      "licensedUsing": 2,
      "licensedInstalled": 3
    },
    "window": {
      "lastNDays": 30
    },
    "swType": "COMMERCIAL",
    "softwareVersion": "5.2.0.31950",
    "computers": {
      "licensedExpiredButUsing": {
        "total": 0,
        "items": []
      },
      "licensedUnused": {
        "total": 1,
        "items": [
          {
            "resourceID": 303,
            "resourceName": "sample-computer-3",
            "domainNetbiosName": "WORKGROUP"
          }
        ]
      },
      "unlicensedInstalled": {
        "total": 0,
        "items": []
      },
      "unlicensedUsing": {
        "total": 0,
        "items": []
      },
      "licensedUnderutilized": {
        "total": 0,
        "items": []
      },
      "licensedUsing": {
        "total": 2,
        "items": [
          {
            "resourceID": 301,
            "resourceName": "sample-computer-1",
            "domainNetbiosName": "WORKGROUP"
          },
          {
            "resourceID": 302,
            "resourceName": "sample-computer-2",
            "domainNetbiosName": "WORKGROUP"
          }
        ]
      }
    }
  }

▼ Show full

Sample Response: HTTP 400

Invalid query parameter

Copied!

  {
    "error_description": "lastNDays must be an integer",
    "error_code": "INVALID_DATA"
  }

▼ Show full

Sample Response: HTTP 401

Caller is not an Inventory Admin or is not managing all computers

Copied!

  {
    "error_description": "Unauthorized access",
    "error_code": "UAC_UNAUTHORIZED"
  }

▼ Show full

Sample Response: HTTP 404

Software not found for the caller

Copied!

  {
    "error_description": "The specified resource was not found",
    "error_code": "RESOURCE_NOT_AVAILABLE"
  }

▼ Show full

Sample Response: HTTP 500

Server error

Copied!

  {
    "error_description": "Internal server error",
    "error_code": "INTERNAL_ERROR"
  }

▼ Show full

Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes

Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.