canonical: https://jentic.com/apis/azure.com/azure-policy-events

# Microsoft Azure PolicyEventsClient

Jentic publishes the only available OpenAPI specification for PolicyEventsClient, keeping it validated and agent-ready. The Azure Policy Insights events API exposes 9 query endpoints under Microsoft.PolicyInsights for retrieving the historical stream of policy evaluation events. Use it to query events at management group, subscription, resource group, individual resource, policy assignment, policy definition, or policy set definition scope, with OData filters for time range, compliance state, and policy identifiers - the audit log behind every Azure Policy compliance state change.

## For AI agents

Query the historical stream of Azure Policy evaluation events at any scope (management group, subscription, resource group, resource, assignment, definition) through 9 OData query endpoints.

## Scope

Does not author policies, manage assignments, or report current compliance state - use for querying the historical stream of policy evaluation events only.

## Capabilities

- Query policy evaluation events at subscription scope across all assignments
- Filter events by time range, compliance state, or policy assignment ID
- Retrieve events for a single resource to investigate when it became non-compliant
- Query events scoped to a specific policy definition or policy set definition
- Aggregate event counts by compliance state for executive reporting
- Walk events at management group scope for cross-subscription compliance audit
- Inspect events for a specific policy assignment to validate that recent changes took effect

## Use cases

### Compliance Drift Investigation

Investigate why a resource is currently flagged non-compliant. Query policy events at the resource scope, filter to the relevant policy assignment, and order by timestamp to see the exact change that flipped the resource from compliant to non-compliant. The events include the operation that triggered evaluation, so the audit trail points back at the deployment, the user or service principal that ran it, and the diff between expected and actual values.

Example prompt: Query policy events for resource '/subscriptions/{id}/resourceGroups/web/providers/Microsoft.Web/sites/app1', filter to NonCompliant events in the last 14 days, and order by timestamp descending

### Tenant-Wide Compliance Reporting

Build a tenant-level compliance report by querying events at management group scope. Group events by subscription, by policy assignment, and by compliance state to produce a board-ready summary of non-compliance hotspots. The OData $apply support enables aggregation server-side so the agent does not have to pull every event row.

Example prompt: Query policy events at management group scope for the last 30 days, group by policyAssignmentId and complianceState, and return a sorted list of the top 10 assignments by NonCompliant count

### Policy Change Validation

After updating a policy definition or assignment, validate that the change is being evaluated correctly. Query events filtered to the assignment, look at evaluations that have occurred since the change took effect, and confirm the expected resources flipped state. This catches regressions where a policyRule update produced different results than intended before they spread across the estate.

Example prompt: Query policy events filtered by policyAssignmentId='/subscriptions/{id}/providers/Microsoft.Authorization/policyAssignments/require-tags' since the assignment update timestamp and report compliance counts

### AI Agent Compliance Investigator

An AI agent supporting a security or governance team can investigate compliance events through Jentic. The agent searches by intent ('query azure policy events'), Jentic returns the queryResults operation with its OData filter schema, and the agent executes the call with managed Azure credentials. The same flow handles drift investigation, change validation, and tenant-wide reporting without the agent learning the seven scope variants of the events endpoint.

Example prompt: Search Jentic for 'query Azure policy events for a resource', load the queryResults schema, and execute it for the supplied resource ID with a 14-day window

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /subscriptions/{subscriptionId}/providers/Microsoft.PolicyInsights/policyEvents/{policyEventsResource}/queryResults | Query policy events at subscription scope |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.PolicyInsights/policyEvents/{policyEventsResource}/queryResults | Query policy events at resource group scope |
| POST | /{resourceId}/providers/Microsoft.PolicyInsights/policyEvents/{policyEventsResource}/queryResults | Query policy events for a specific resource |
| POST | /providers/{managementGroupsNamespace}/managementGroups/{managementGroupName}/providers/Microsoft.PolicyInsights/policyEvents/{policyEventsResource}/queryResults | Query policy events at management group scope |
| POST | /subscriptions/{subscriptionId}/providers/{authorizationNamespace}/policyAssignments/{policyAssignmentName}/providers/Microsoft.PolicyInsights/policyEvents/{policyEventsResource}/queryResults | Query policy events for a specific policy assignment |
| POST | /subscriptions/{subscriptionId}/providers/{authorizationNamespace}/policyDefinitions/{policyDefinitionName}/providers/Microsoft.PolicyInsights/policyEvents/{policyEventsResource}/queryResults | Query policy events for a specific policy definition |

## Key resources

- **PolicyEvents** — Query the historical stream of policy evaluation events at any scope
- **QueryResults** — Apply OData filters and groupings to events

## Why Jentic

- **Setup:** Wiring the PolicyEventsClient by hand means getting an Azure AD token from login.microsoftonline.com, sending every request to management.azure.com with the right api-version, and choosing among several scope-specific queryResults paths for subscription, resource group, resource, and management group yourself. Through Jentic you install once, import PolicyEventsClient from the API Directory, store the Azure AD credential once, and your agent calls it.
- **Permission scoping:** This API puts the scope in the URL path (subscription, resource group, resource, or management group) while the event filters travel in the request body, so limit the agent to the operations it needs, such as querying policy events at a subscription scope. You choose those operations, so a broader management-group query is not included unless you add it.
- **Credential handling:** Your Azure AD credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'query Azure policy events for a resource' or 'find non-compliant policy events', and Jentic returns the matching scope-specific queryResults operation with its input schema so the agent does not pick between the scope variants by hand.

## Related APIs

- **Azure Policy States** — Query current compliance state instead of the historical event stream.
- **Azure Policy** — Author and assign the policies whose evaluation history this API exposes.
- **Azure Policy Tracked Resources** — List resources modified by deployIfNotExists or modify policies.
- **Azure Monitor** — Generic activity log queries that include policy evaluations alongside other ARM activity.

## FAQ

### Why is there no official OpenAPI spec for PolicyEventsClient?

Microsoft Azure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PolicyEventsClient via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Azure Policy Events API use?

It uses Azure Active Directory OAuth 2.0 against https://management.azure.com/ with the user_impersonation scope. The caller needs Reader on Microsoft.PolicyInsights at the queried scope. Jentic stores service principal credentials encrypted and issues short-lived bearer tokens at execution time.

### Can I filter events by policy assignment through this API?

Yes. POST to /subscriptions/{id}/providers/Microsoft.Authorization/policyAssignments/{name}/providers/Microsoft.PolicyInsights/policyEvents/default/queryResults with an OData $filter on timestamp and complianceState in the request body. The response includes the resource ID, evaluation result, and the policy definition that fired.

### What are the rate limits for the Policy Events API?

Azure Resource Manager applies subscription-level throttling at roughly 1,200 reads per hour. Event queries can return large result sets; use $top and $skiptoken pagination for windows wider than a few hours to stay under per-call response size limits.

### How do I investigate a non-compliant resource through Jentic?

Run pip install jentic and search for 'query azure policy events for a resource'. Jentic returns the queryResults operation; load its schema and execute it with the resource ID, a 14-day timestamp filter, and complianceState eq 'NonCompliant'.

### How far back does this API retain policy events?

Azure Policy events are retained for 30 days. For longer-term compliance history, export events to Log Analytics or Storage via diagnostic settings on the Microsoft.PolicyInsights resource provider.

### Can I limit what my agent is allowed to do with the Azure Policy Events API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent can use, and this API encodes the scope directly in the URL path, so you can grant only the queryResults operation you need, such as querying policy events at a single subscription scope. If you do not add the management-group query operation, the agent cannot walk events across all child subscriptions. The event filters, like a timestamp range or a complianceState value, still travel in the request body, so you control both the operation and the breadth of access from your own instance.