# 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`

## Request URL

`https://{server-hostname}:8383/dcapi/inventory/software/{softwareID}/license/usageInsights`

## Scope

`Inventory.READ`

## Header

`Authorization: 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/onpremise/inventory-get-installed-software-list.html) API.

## Sample Request

```curl
curl --request GET \
  --url https://appdomain/dcapi/inventory/software/{softwareID}/license/usageInsights \
  --header 'Accept: application/licenseUsageInsightsResponse.v1+json' \
  --header 'Authorization:  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 Response: 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"
        }
      ]
    }
  }
}
```

## Sample Response: HTTP 400

Invalid query parameter

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

## Sample Response: HTTP 401

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

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

## Sample Response: HTTP 404

Software not found for the caller

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

## Sample Response: HTTP 500

Server error

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

## Rate Limits

![](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.