# 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).

## Endpoint

`GET /dcapi/inventory/software/{softwareID}/license/usageInsights`

## Request

### Request URL

`https://[{serverurl}](https://www.manageengine.com/products/desktop-central/help/api/cloud/oauth-authentication-endpoint-domain.html)/dcapi/inventory/software/{softwareID}/license/usageInsights`

### Scope

`DesktopCentralCloud.Inventory.READ`

### Header

`Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52`

### Request Parameters

#### Request Headers

- **Accept** `string` — **Mandatory**
  - `application/licenseUsageInsightsResponse.v1+json`

#### Path Parameters

- **softwareID** `string` — **Mandatory**
  - Software identifier. Obtain from the response of the [Get Installed Software List](https://www.manageengine.com/products/desktop-central/help/api/cloud/inventory-get-installed-software-list.html) API.

#### Query Parameters

- **lastNDays** `string` — Optional
  - Time window in days (1-90). Defaults to 90 when omitted; values above 90 are silently clamped to 90.
- **maxRunTimeSeconds** `string` — Optional
  - Any installed computer with windowed runtime less than or equal to this value falls into the licensedUnderutilized bucket.
- **domainNetbiosName** `string` — Optional
  - Domain name to filter computers. Obtain from the response of the [Get Computers List](https://www.manageengine.com/products/desktop-central/help/api/cloud/computers-getcomputers.html) API.
- **branchOfficeID** `string` — Optional
  - Branch Office ID to filter computers. Obtain from the response of the [Get Remote Office List](https://www.manageengine.com/products/desktop-central/help/api/cloud/remote-offices-getremoteoffices.html) API.
- **customGroupID** `string` — Optional
  - Custom group ID to filter computers. Obtain from the response of the [Get Custom Group List](https://www.manageengine.com/products/desktop-central/help/api/cloud/custom-groups-get-cglist.html) API.
- **osPlatform** `string` — Optional
  - Filter computers by OS platform. Allowed values: 1 - Windows, 2 - Mac

### Sample Request

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

## Response Parameters

### HTTP Code 200

Response body: `application/json`

- `JSON Object`
  - **window** `JSON 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)
  - **softwareID** `long`
    - Echo of the path parameter
  - **softwareName** `string`
    - Display name from InvSW.DISPLAY_NAME
  - **softwareVersion** `string`
    - Version from InvSW.SOFTWARE_VERSION
  - **swType** `string`
    - Software type label - COMMERCIAL, NON_COMMERCIAL or UNIDENTIFIED
  - **meteringConfigured** `boolean`
    - True if at least one metering rule exists for this software
  - **meteringRules** `array`
    - Configured metering rules for this software. Each rule carries appDefinitionID, ruleName, fileName, osPlatform and status (boolean - true when the rule is enabled)
  - **license** `JSON 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
  - **counts** `JSON 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.
  - **computers** `JSON Object`
    - Map of bucket name to {total, items[]} where each item carries resourceID, resourceName and domainNetbiosName. Buckets: licensedUsing, licensedUnused, licensedUnderutilized, unlicensedUsing, unlicensedInstalled, licensedExpiredButUsing. Every bucket is always present (empty buckets return {total:0, items:[]})
  - **notice** `string`
    - Optional advisory message - present only when lastNDays was clamped

### HTTP Code 400

Response body: `application/json`

- `JSON Object`
  - **error_code** `string`
    - CUSTOMER_HEADER_MISSING - MSP environment requires X-Customer header
  - **error_description** `string`
    - Missing customer header error message

### HTTP Code 401

Response body: `application/json`

- `JSON Object`
  - **error_code** `string`
    - UAC_UNAUTHORIZED - user lacks the required uem-roles or credentials are missing
  - **error_description** `string`
    - Authentication or authorization failure reason

### HTTP Code 404

Response body: `application/json`

- `JSON Object`
  - **error_code** `string`
    - RESOURCE_NOT_AVAILABLE - the specified resourceID does not exist or is not accessible
  - **error_description** `string`
    - Resource not found message

### HTTP Code 500

Response body: `application/json`

- `JSON Object`
  - **error_code** `string`
    - INTERNAL_ERROR - unexpected exception in the service layer
  - **error_description** `string`
    - Internal server error message

## Possible Response Codes

- **200** `HTTP code`
- **400** `HTTP code`
- **401** `HTTP code`
- **404** `HTTP code`
- **500** `HTTP code`

## Sample Responses

### HTTP 200

License × usage insights for a software

```json
{
  "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"
        }
      ]
    }
  }
}
```

### HTTP 400

Invalid query parameter

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

### HTTP 401

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

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

### HTTP 404

Software not found for the caller

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

### HTTP 500

Server error

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

## Rate Limit

![](https://www.zohowebstatic.com/sites/zweb/images/people/ico-help.png)

**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.