Skip to content

Commit becf72f

Browse files
wukchungCopilotsanchariroy9197FaithOmbongi
authored
Add Azure AD Premium License Insight API documentation (#28356)
* Add Azure AD Premium License Insight API documentation Add beta API documentation for the azureADPremiumLicenseInsight resource type and related endpoints. This includes: - GET /reports/azureADPremiumLicenseInsight - GET /reports/azureADPremiumLicenseInsightHistory - Resource types: azureADPremiumLicenseInsight, azureADPremiumLicenseInsightHistory - Complex types: azureADPremiumFeatureUtilization, azureADPremiumP1FeatureUtilizations, azureADPremiumP2FeatureUtilizations, internetAccessFeatureUtilizations, privateAccessFeatureUtilizations - Permissions include files - TOC mapping entries AB#3527791 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Replace hand-authored docs with autogenerated stubs for license utilization API - Replace API file with autogenerated stub naming (azureadpremiumlicenseinsight-get.md) - Replace permission include with autogenerated naming - Update all resource files to match autogenerated stub structure - Remove azureADPremiumLicenseInsightHistory docs (entity still hidden, no stubs) - Update TOC mapping to remove hidden history entity - Fill TODO fields with descriptions from CSDL schema annotations * Address content review feedback: licensing, RBAC, query params, descriptions * Add reportroot relationship and changelog entry for license utilization * Add What's New entry for license utilization API (beta) * Apply suggestion from @FaithOmbongi Co-authored-by: Faith Moraa Ombongi <ombongi.moraa.fe@gmail.com> * Update changelog date to 2026-04-16 and remove What's New entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Readd what's new --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Sanchari Roy <sanchariroy@microsoft.com> Co-authored-by: Faith Moraa Ombongi <ombongi.moraa.fe@gmail.com>
1 parent 673a787 commit becf72f

12 files changed

Lines changed: 527 additions & 0 deletions

‎api-reference/beta/api/azureadpremiumlicenseinsight-get.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: "Get azureADPremiumLicenseInsight"
3+
description: "Get the premium license utilization insight for the tenant."
4+
author: "sanchariroy"
5+
ms.date: 03/13/2026
6+
ms.localizationpriority: medium
7+
ms.subservice: "entra-monitoring-health"
8+
doc_type: apiPageType
9+
---
10+
11+
# Get azureADPremiumLicenseInsight
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Get the premium license utilization insight for the tenant. This API returns data about how many premium licenses are entitled and how the associated P1 and P2 features are being used. The calling tenant must have at least one Microsoft Entra ID P1 or P2 license. Tenants without a premium license receive a `403 Forbidden` response with the `missingLicense` error code.
18+
19+
[!INCLUDE [national-cloud-support](../../includes/global-only.md)]
20+
21+
## Permissions
22+
23+
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
24+
25+
<!-- {
26+
"blockType": "permissions",
27+
"name": "azureadpremiumlicenseinsight-get-permissions"
28+
}
29+
-->
30+
[!INCLUDE [permissions-table](../includes/permissions/azureadpremiumlicenseinsight-get-permissions.md)]
31+
32+
> [!IMPORTANT]
33+
> In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role with a supported role permission. The following least privileged roles are supported for this operation.
34+
> - Application Administrator
35+
> - Cloud Application Administrator
36+
> - Global Reader
37+
> - Reports Reader
38+
> - Security Administrator
39+
> - Security Operator
40+
> - Security Reader
41+
42+
## HTTP request
43+
44+
<!-- {
45+
"blockType": "ignored"
46+
}
47+
-->
48+
``` http
49+
GET /reports/azureADPremiumLicenseInsight
50+
```
51+
52+
## Optional query parameters
53+
54+
This method supports the `$select` OData query parameter to help customize the response. For general information, see [OData query parameters](/graph/query-parameters).
55+
56+
## Request headers
57+
58+
|Name|Description|
59+
|:---|:---|
60+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
61+
62+
## Request body
63+
64+
Don't supply a request body for this method.
65+
66+
## Response
67+
68+
If successful, this method returns a `200 OK` response code and an [azureADPremiumLicenseInsight](../resources/azureadpremiumlicenseinsight.md) object in the response body.
69+
70+
## Examples
71+
72+
### Request
73+
74+
The following example shows a request.
75+
<!-- {
76+
"blockType": "request",
77+
"name": "get_azureadpremiumlicenseinsight"
78+
}
79+
-->
80+
```msgraph-interactive
81+
GET https://graph.microsoft.com/beta/reports/azureADPremiumLicenseInsight
82+
```
83+
84+
85+
### Response
86+
87+
The following example shows the response.
88+
>**Note:** The response object shown here might be shortened for readability.
89+
<!-- {
90+
"blockType": "response",
91+
"truncated": true,
92+
"@odata.type": "microsoft.graph.azureADPremiumLicenseInsight"
93+
}
94+
-->
95+
``` http
96+
HTTP/1.1 200 OK
97+
Content-Type: application/json
98+
99+
{
100+
"id": "00000000-0000-0000-0000-000000000000",
101+
"entitledP1LicenseCount": 100,
102+
"entitledP2LicenseCount": 50,
103+
"entitledTotalLicenseCount": 150,
104+
"p1FeatureUtilizations": {
105+
"conditionalAccess": {
106+
"userCount": 85
107+
},
108+
"conditionalAccessGuestUsers": {
109+
"userCount": 12
110+
}
111+
},
112+
"p2FeatureUtilizations": {
113+
"riskBasedConditionalAccess": {
114+
"userCount": 30
115+
},
116+
"riskBasedConditionalAccessGuestUsers": {
117+
"userCount": 5
118+
}
119+
},
120+
"privateAccessFeatureUtilizations": {
121+
"privateAccess": {
122+
"userCount": 20
123+
}
124+
},
125+
"internetAccessFeatureUtilizations": {
126+
"internetAccess": {
127+
"userCount": 45
128+
},
129+
"internetAccessM365": {
130+
"userCount": 38
131+
}
132+
}
133+
}
134+
```

‎api-reference/beta/includes/permissions/azureadpremiumlicenseinsight-get-permissions.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Automatically generated file. DO NOT MODIFY
3+
ms.topic: include
4+
ms.localizationpriority: medium
5+
---
6+
7+
|Permission type|Least privileged permissions|Higher privileged permissions|
8+
|:---|:---|:---|
9+
|Delegated (work or school account)|Reports.Read.All|Not available.|
10+
|Delegated (personal Microsoft account)|Not supported.|Not supported.|
11+
|Application|Reports.Read.All|Not available.|

‎api-reference/beta/resources/azureadpremiumfeatureutilization.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "azureADPremiumFeatureUtilization resource type"
3+
description: "Represents the utilization count for a single Microsoft Entra ID premium feature."
4+
author: "sanchariroy"
5+
ms.date: 03/13/2026
6+
ms.localizationpriority: medium
7+
ms.subservice: "entra-monitoring-health"
8+
doc_type: resourcePageType
9+
---
10+
11+
# azureADPremiumFeatureUtilization resource type
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Represents the utilization count for a single Microsoft Entra ID premium feature. Contains the number of users who have used the feature. Used by properties of the [azureADPremiumP1FeatureUtilizations](azureadpremiump1featureutilizations.md) and [azureADPremiumP2FeatureUtilizations](azureadpremiump2featureutilizations.md) resources.
18+
19+
20+
## Properties
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|userCount|Int64|The number of users who have used this premium feature.|
24+
25+
## Relationships
26+
None.
27+
28+
## JSON representation
29+
The following JSON representation shows the resource type.
30+
<!-- {
31+
"blockType": "resource",
32+
"@odata.type": "microsoft.graph.azureADPremiumFeatureUtilization"
33+
}
34+
-->
35+
``` json
36+
{
37+
"@odata.type": "#microsoft.graph.azureADPremiumFeatureUtilization",
38+
"userCount": "Integer"
39+
}
40+
```

‎api-reference/beta/resources/azureadpremiumlicenseinsight.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: "azureADPremiumLicenseInsight resource type"
3+
description: "Provides insight into the Microsoft Entra ID P1 and P2 premium license utilization for a tenant."
4+
author: "sanchariroy"
5+
ms.date: 03/13/2026
6+
ms.localizationpriority: medium
7+
ms.subservice: "entra-monitoring-health"
8+
doc_type: resourcePageType
9+
---
10+
11+
# azureADPremiumLicenseInsight resource type
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Provides insight into the Microsoft Entra ID P1 and P2 premium license utilization for a tenant. This resource shows how many premium licenses are entitled and how the associated premium features are being used.
18+
19+
Inherits from [entity](../resources/entity.md)
20+
21+
## Methods
22+
|Method|Return type|Description|
23+
|:---|:---|:---|
24+
|[Get](../api/azureadpremiumlicenseinsight-get.md)|[azureADPremiumLicenseInsight](../resources/azureadpremiumlicenseinsight.md)|Get the premium license utilization insight for the tenant.|
25+
26+
## Properties
27+
|Property|Type|Description|
28+
|:---|:---|:---|
29+
|entitledP1LicenseCount|Int64|The number of Microsoft Entra ID P1 licenses entitled to the tenant.|
30+
|entitledP2LicenseCount|Int64|The number of Microsoft Entra ID P2 licenses entitled to the tenant.|
31+
|entitledTotalLicenseCount|Int64|The total number of Microsoft Entra ID premium licenses (P1 + P2) entitled to the tenant.|
32+
|id|String|The unique identifier for the entity. Inherited from [entity](../resources/entity.md).|
33+
|internetAccessFeatureUtilizations|[internetAccessFeatureUtilizations](../resources/internetaccessfeatureutilizations.md)|The utilization data for Microsoft Entra Internet Access features.|
34+
|p1FeatureUtilizations|[azureADPremiumP1FeatureUtilizations](../resources/azureadpremiump1featureutilizations.md)|The utilization data for Microsoft Entra ID P1 features.|
35+
|p2FeatureUtilizations|[azureADPremiumP2FeatureUtilizations](../resources/azureadpremiump2featureutilizations.md)|The utilization data for Microsoft Entra ID P2 features.|
36+
|privateAccessFeatureUtilizations|[privateAccessFeatureUtilizations](../resources/privateaccessfeatureutilizations.md)|The utilization data for Microsoft Entra Private Access features.|
37+
38+
## Relationships
39+
None.
40+
41+
## JSON representation
42+
The following JSON representation shows the resource type.
43+
<!-- {
44+
"blockType": "resource",
45+
"keyProperty": "id",
46+
"@odata.type": "microsoft.graph.azureADPremiumLicenseInsight",
47+
"openType": false
48+
}
49+
-->
50+
``` json
51+
{
52+
"@odata.type": "#microsoft.graph.azureADPremiumLicenseInsight",
53+
"entitledP1LicenseCount": "Integer",
54+
"entitledP2LicenseCount": "Integer",
55+
"entitledTotalLicenseCount": "Integer",
56+
"id": "String (identifier)",
57+
"internetAccessFeatureUtilizations": {
58+
"@odata.type": "microsoft.graph.internetAccessFeatureUtilizations"
59+
},
60+
"p1FeatureUtilizations": {
61+
"@odata.type": "microsoft.graph.azureADPremiumP1FeatureUtilizations"
62+
},
63+
"p2FeatureUtilizations": {
64+
"@odata.type": "microsoft.graph.azureADPremiumP2FeatureUtilizations"
65+
},
66+
"privateAccessFeatureUtilizations": {
67+
"@odata.type": "microsoft.graph.privateAccessFeatureUtilizations"
68+
}
69+
}
70+
```

‎api-reference/beta/resources/azureadpremiump1featureutilizations.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "azureADPremiumP1FeatureUtilizations resource type"
3+
description: "Represents the utilization data for Microsoft Entra ID P1 premium features."
4+
author: "sanchariroy"
5+
ms.date: 03/13/2026
6+
ms.localizationpriority: medium
7+
ms.subservice: "entra-monitoring-health"
8+
doc_type: resourcePageType
9+
---
10+
11+
# azureADPremiumP1FeatureUtilizations resource type
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Represents the utilization data for Microsoft Entra ID P1 premium features. Each property contains a user count indicating how many users in the tenant have used that P1 feature. Used by the **p1FeatureUtilizations** property of the [azureADPremiumLicenseInsight](azureadpremiumlicenseinsight.md) resource.
18+
19+
20+
## Properties
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|conditionalAccess|[azureADPremiumFeatureUtilization](../resources/azureadpremiumfeatureutilization.md)|The utilization data for the Conditional Access feature.|
24+
|conditionalAccessGuestUsers|[azureADPremiumFeatureUtilization](../resources/azureadpremiumfeatureutilization.md)|The utilization data for the Conditional Access feature applied to guest users.|
25+
26+
## Relationships
27+
None.
28+
29+
## JSON representation
30+
The following JSON representation shows the resource type.
31+
<!-- {
32+
"blockType": "resource",
33+
"@odata.type": "microsoft.graph.azureADPremiumP1FeatureUtilizations"
34+
}
35+
-->
36+
``` json
37+
{
38+
"@odata.type": "#microsoft.graph.azureADPremiumP1FeatureUtilizations",
39+
"conditionalAccess": {
40+
"@odata.type": "microsoft.graph.azureADPremiumFeatureUtilization"
41+
},
42+
"conditionalAccessGuestUsers": {
43+
"@odata.type": "microsoft.graph.azureADPremiumFeatureUtilization"
44+
}
45+
}
46+
```

‎api-reference/beta/resources/azureadpremiump2featureutilizations.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "azureADPremiumP2FeatureUtilizations resource type"
3+
description: "Represents the utilization data for Microsoft Entra ID P2 premium features."
4+
author: "sanchariroy"
5+
ms.date: 03/13/2026
6+
ms.localizationpriority: medium
7+
ms.subservice: "entra-monitoring-health"
8+
doc_type: resourcePageType
9+
---
10+
11+
# azureADPremiumP2FeatureUtilizations resource type
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Represents the utilization data for Microsoft Entra ID P2 premium features. Each property contains a user count indicating how many users in the tenant have used that P2 feature. Used by the **p2FeatureUtilizations** property of the [azureADPremiumLicenseInsight](azureadpremiumlicenseinsight.md) resource.
18+
19+
20+
## Properties
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|riskBasedConditionalAccess|[azureADPremiumFeatureUtilization](../resources/azureadpremiumfeatureutilization.md)|The utilization data for the risk-based Conditional Access feature.|
24+
|riskBasedConditionalAccessGuestUsers|[azureADPremiumFeatureUtilization](../resources/azureadpremiumfeatureutilization.md)|The utilization data for the risk-based Conditional Access feature applied to guest users.|
25+
26+
## Relationships
27+
None.
28+
29+
## JSON representation
30+
The following JSON representation shows the resource type.
31+
<!-- {
32+
"blockType": "resource",
33+
"@odata.type": "microsoft.graph.azureADPremiumP2FeatureUtilizations"
34+
}
35+
-->
36+
``` json
37+
{
38+
"@odata.type": "#microsoft.graph.azureADPremiumP2FeatureUtilizations",
39+
"riskBasedConditionalAccess": {
40+
"@odata.type": "microsoft.graph.azureADPremiumFeatureUtilization"
41+
},
42+
"riskBasedConditionalAccessGuestUsers": {
43+
"@odata.type": "microsoft.graph.azureADPremiumFeatureUtilization"
44+
}
45+
}
46+
```

‎api-reference/beta/resources/internetaccessfeatureutilizations.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "internetAccessFeatureUtilizations resource type"
3+
description: "Represents the aggregated utilization metrics for Microsoft Entra Internet Access features."
4+
author: "sanchariroy"
5+
ms.date: 03/13/2026
6+
ms.localizationpriority: medium
7+
ms.subservice: "entra-monitoring-health"
8+
doc_type: resourcePageType
9+
---
10+
11+
# internetAccessFeatureUtilizations resource type
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Represents the aggregated utilization metrics for Microsoft Entra Internet Access features. Used by the **internetAccessFeatureUtilizations** property of the [azureADPremiumLicenseInsight](azureadpremiumlicenseinsight.md) resource.
18+
19+
20+
## Properties
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|internetAccess|[azureADPremiumFeatureUtilization](../resources/azureadpremiumfeatureutilization.md)|The utilization data for the Microsoft Entra Internet Access feature.|
24+
|internetAccessM365|[azureADPremiumFeatureUtilization](../resources/azureadpremiumfeatureutilization.md)|The utilization data for the Microsoft Entra Internet Access for Microsoft 365 feature.|
25+
26+
## Relationships
27+
None.
28+
29+
## JSON representation
30+
The following JSON representation shows the resource type.
31+
<!-- {
32+
"blockType": "resource",
33+
"@odata.type": "microsoft.graph.internetAccessFeatureUtilizations"
34+
}
35+
-->
36+
``` json
37+
{
38+
"@odata.type": "#microsoft.graph.internetAccessFeatureUtilizations",
39+
"internetAccess": {
40+
"@odata.type": "microsoft.graph.azureADPremiumFeatureUtilization"
41+
},
42+
"internetAccessM365": {
43+
"@odata.type": "microsoft.graph.azureADPremiumFeatureUtilization"
44+
}
45+
}
46+
```

0 commit comments

Comments
 (0)