|
| 1 | +--- |
| 2 | +title: "Use the Tenant Configuration Management APIs in Microsoft Graph" |
| 3 | +description: "Learn how to use the Tenant Configuration Management APIs in Microsoft Graph to control and manage configuration settings for an entire organization." |
| 4 | +ms.localizationpriority: high |
| 5 | +author: "swatyario" |
| 6 | +ms.subservice: "tenant-configuration-management" |
| 7 | +doc_type: conceptualPageType |
| 8 | +ms.date: 01/19/2026 |
| 9 | +--- |
| 10 | + |
| 11 | +# Use the Tenant Configuration Management APIs in Microsoft Graph |
| 12 | + |
| 13 | +Namespace: microsoft.graph |
| 14 | + |
| 15 | +The Tenant Configuration Management (TCM) APIs allow administrators to control and manage configuration settings across a single workload or multiple workloads within the organization. |
| 16 | + |
| 17 | +The tenant configuration APIs need admins to first add TCM service principal to their tenant and then grant permissions to it. This is a pre-requisite step. Read more here: [Set up authentication for Tenant Configuration Management APIs](/graph/utcm-authentication-setup) |
| 18 | + |
| 19 | +## Authorization |
| 20 | + |
| 21 | +To call the TCM APIs in Microsoft Graph, your app needs to acquire an access token. For details about access tokens, see [Get access tokens to call Microsoft Graph](/graph/auth/). Your app also needs the appropriate permissions. For more information, see [Microsoft Graph permissions reference](/graph/permissions-reference). |
| 22 | + |
| 23 | +## Tenant monitoring APIs |
| 24 | + |
| 25 | +The tenant [monitoring](../resources/configurationmonitor.md) APIs in TCM allow administrators to create one or more monitors, review their monitoring results, and get information about all active drifts in a tenant. Administrators can then resolve these [drifts](../resources/configurationdrift.md) by using the relevant admin centers or other available methods. |
| 26 | + |
| 27 | +## Snapshot APIs |
| 28 | + |
| 29 | +The [snapshot](../resources/configurationsnapshotjob.md) APIs in TCM allow administrators to extract the current tenant configuration settings. This process allows administrators to get a baseline that represents the desired tenant configuration and serves as the foundation for periodic tenant monitoring. |
| 30 | + |
| 31 | +## Common use cases |
| 32 | + |
| 33 | +The following table lists common use cases for the TCM APIs. |
| 34 | + |
| 35 | +| Use case | REST resource | See also | |
| 36 | +| :---------------------------------------------------------- | :---------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- | |
| 37 | +| Get a baseline and create a snapshot job | [configurationBaseline](../resources/configurationbaseline.md) | [configurationBaseline methods](../resources/configurationbaseline.md#methods) | |
| 38 | +| List and get drifts | [configurationDrift](../resources/configurationdrift.md) | [configurationDrift methods](../resources/configurationdrift.md#methods) | |
| 39 | +| Create and manage monitors | [configurationMonitor](../resources/configurationmonitor.md) | [configurationMonitor methods](../resources/configurationmonitor.md#methods) | |
| 40 | +| List and get monitoring results | [configurationMonitoringResult](../resources/configurationmonitoringresult.md) | [configurationMonitoringResult methods](../resources/configurationmonitoringresult.md#methods) | |
| 41 | +| List, get, and delete snapshot jobs | [configurationSnapshotJob](../resources/configurationsnapshotjob.md) | [configurationSnapshotJob methods](../resources/configurationsnapshotjob.md#methods) | |
| 42 | + |
| 43 | +## API limits |
| 44 | + |
| 45 | +### Tenant monitoring |
| 46 | + |
| 47 | +The following API limits apply to the [configurationMonitor](../resources/configurationmonitor.md) API: |
| 48 | + |
| 49 | +- You can create up to 30 **configurationMonitor** objects per tenant. |
| 50 | +- Each configurationMonitor runs at a **fixed interval of six hours**. A monitor cannot be configured to run at any other frequency. |
| 51 | +- An administrator can monitor up to **800 configuration resources per day per tenant**, across all monitors. Administrators decide how to use this quota—through a single monitor or multiple monitors. Example: If an admin includes **20 transport rules** and **30 conditional access policies** in a monitor's baseline, that monitor tracks **50 resources per cycle**. Since the monitor runs every six hours (**4 cycles/day**), this results in **200 monitored resources per day**. Additional monitors can be created until the daily **800‑resource** limit is reached. |
| 52 | +- When an administrator updates the baseline of an existing monitor, **all previously generated monitoring results and detected drifts for that monitor** are automatically deleted. |
| 53 | + |
| 54 | +### Drifts |
| 55 | + |
| 56 | +The following API limits apply to the [configurationDrift](../resources/configurationdrift.md) API: |
| 57 | + |
| 58 | +- All active drifts are retained and available for administrators to review at any time. |
| 59 | +- Each fixed drift is deleted 30 days after it is resolved. |
| 60 | + |
| 61 | +### Snapshot |
| 62 | + |
| 63 | +The following API limits apply to the [configurationSnapshotJob](../resources/configurationsnapshotjob.md) API: |
| 64 | + |
| 65 | +- You can extract a maximum of 20000 resources per tenant per month. This is a cumulative limit across all snapshots. |
| 66 | +- There is **no maximum number of snapshots** you can create per day or per month. You may generate as many snapshots as needed, as long as the **total number of resources extracted** stays within the **20,000-resource monthly quota** for the tenant. |
| 67 | +- A maximum of 12 snapshot jobs are visible to the administrator. If the administrator wants to create more snapshot jobs, they have to delete one or more of the existing jobs. |
| 68 | +- A snapshot is retained for a maximum of seven days, after which it is automatically deleted. |
| 69 | + |
| 70 | +## Next steps |
| 71 | + |
| 72 | +Use the Microsoft Graph TCM APIs to control and manage configuration settings across one or more workloads within an organization. To learn more: |
| 73 | + |
| 74 | +- Explore the resources and methods that are most helpful to your scenario. |
| 75 | +- Try the API in the [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). |
| 76 | + |
| 77 | +## Related content |
| 78 | + |
| 79 | +[Overview of the Tenant Configuration Management APIs in Microsoft Graph](/graph/unified-tenant-configuration-management-concept-overview) |
| 80 | + |
| 81 | +[Set up authentication for Tenant Configuration Management APIs](/graph/utcm-authentication-setup) |
0 commit comments