Microsoft 365 Copilot Cost Management API overview

The Microsoft 365 Copilot Cost Management API helps administrators govern and observe tenant consumption of Copilot and AI credits through Microsoft Graph, rooted at /copilot/costManagement. The contract is unit-aware and credit-denominated. It covers the tenant credit balance snapshot, spending policy management, group audience scoping, per-service settings, notify-only threshold alerts and their recipients, per-user consumption balances, the review of users' credit requests, and usage reports that break down consumption by user, security group, governed service, and funding class.

The API is credit-denominated and deliberately excludes purchase forecasts. It doesn't return any currency, invoice, price, or settlement amounts.

Key capabilities

• Read the tenant-wide credit balance snapshot, with one row per billing method.
• Create, read, update, and delete spending policies that cap Copilot Credits consumption for an audience.
• Scope a policy to every user in the tenant (allUsersSpendingPolicy) or to selected groups (selectedGroupsSpendingPolicy).
• Manage a policy's group audience through $ref reference links.
• Configure per-service settings that govern or exclude individual AI services within a policy.
• Configure notify-only threshold alerts and manage their recipients.
• Diagnose a user's per-service consumption balance and understand why a user can or can't consume a service.
• List, review, approve, or reject users' requests for Copilot credits, individually or in bulk.
• Report consumption for one completed UTC day by user, security group, and governed service, with ranking and paging.
• Report a calendar month's consumption by funding class (prepaid, pay-as-you-go, unbilled overage, and non-billable).
• Read one user's raw usage detail over a timestamp window, broken down by service and session.

Example scenarios

• An administrator sets a monthly credit cap for a pilot group and alerts admins when usage reaches 80 percent.
• An administrator adds or removes a governed service on an existing policy.
• A support administrator diagnoses why a user can no longer consume a service by reading that user's per-service balance.
• A FinOps reader lists the tenant's enabled spending policies and reviews their configured limits.
• An AI administrator reviews pending credit requests for Work IQ and approves them in bulk.
• A FinOps analyst splits yesterday's consumption by service to see where credits went across AI experiences.
• A billing administrator closes a month by reviewing its consumption by funding class, including unbilled overage.
• A FinOps analyst or business unit lead ranks the highest-consuming users or security groups for a day.
• A support administrator inspects one user's raw usage sessions over a time window.

Personas and roles

Target personas include the AI Administrator and License Administrator for policy management; the FinOps/Global Reader and Billing Administrator for reads; and the Support/Helpdesk administrator for per-user diagnostics. For usage reports, target personas include the FinOps analyst and Billing Administrator for the service and funding reports, and the FinOps analyst and business unit (BU) lead for the user and group rankings. Creating a spending policy also requires the Billing Administrator or Global Administrator directory role at runtime.

Billing Administrators, Global Administrators, AI Administrators, Global Readers, and AI Readers can read credit requests. Global Administrators, Billing Administrators, and AI Administrators can approve or reject them.

Permissions

This API uses the CopilotCostManagement-* permission family. Most operations support only delegated (work or school account) permissions. The tenant credit balance read (getTenantCreditBalance) also supports the CopilotCostManagement.Read.All application permission, and the service and funding usage reports also support the CopilotCostManagement-Reports.Read.All and CopilotCostManagement.Read.All application permissions. Personal Microsoft accounts aren't supported. Choose the least privileged permission for each operation.

API list

Concurrency and removal semantics

• To mutate an existing policy and its child resources (service settings and reference links), include an If-Match header with the parent policy's ETag. Service settings and reference links don't have their own ETag. The parent policy manages concurrency and appears as parentEtag on a service setting. When you create a policy, it has no existing ETag and doesn't use If-Match.
• The serviceSettings collection doesn't support DELETE. Set state to disabled to remove a service. The entry stays in that state.
• Manage the assignedGroups and recipients relationships as reference navigation properties with $ref add and remove.
• Credit requests carry their own strong ETag, returned as @odata.etag and in the ETag response header. Update creditRequest requires an If-Match header; the batchRecordDecisions action takes a per-item etag instead.
• A credit request decision that matches the current state is a no-op that preserves the ETag, decisionBy, and timestamps. The ETag is still checked, so a same-state decision with a stale ETag fails with preconditionFailed.
• Credit requests can't be created or deleted through the API. Users create them outside Microsoft Graph, and the service retains them according to its retention policy.

Usage report time selectors and paging

Usage reports live under /copilot/costManagement/usageReports. Every usage report request requires a time selector, supplied as query parameters. Requests without the required selectors are rejected with a 400 unsupportedQuery response.

Invalid selectors are rejected, not clamped. Current-day, future, and multi-day ranges on the completed-UTC-day reports return a 400 response, as do timestamp windows that currently don't meet the timestamp-window limits in the table. Validation doesn't enforce an oldest permitted startDate or month.

• Paging. The user, group, and service usage records and the user usage sessions use server-driven paging with $skiptoken; $skip isn't supported. Follow the complete @odata.nextLink URL unchanged. The continuation keeps the original selectors, filter, and order, but it isn't a point-in-time snapshot. Later pages read current data, so rows can repeat or be missed between pages. A nextLink whose dates differ from the original request is rejected with a 400 response. On the user, group, and service usage records, $top accepts an integer from 1 through 100 with a default of 10, and values outside that range are rejected, not capped. The user usage sessions have a separate default page size of 20 and a maximum of 100. Funding usage records and the user usage services aren't paged.
• Filtering. The user, group, and service usage records support $filter on userId, groupId, and serviceId respectively, by using only the eq operator. Other operators, such as in, aren't supported.
• Ordering. Only consumedQuantity supports $orderby. Ties are broken internally, and ordering on the dimension key isn't supported.
• Units. Every quantity carries a unit, currently copilotCredit. No currency, invoice, price, or settlement amounts are returned.
• Processed versus raw. userUsageRecords returns processed consumption for one completed UTC day that you can rank across users. userUsageDetails returns one user's raw, billable-flagged usage over a timestamp window, with service and session breakdowns. The two measurements, including their sessionCount values, aren't guaranteed to be equal.
• Not-readable parents. GET /copilot/costManagement/usageReports returns a 404 response and carries no data. GET /copilot/costManagement/usageReports/userUsageDetails isn't listable; read the detail by user ID instead.

Error conditions

Error responses use the standard OData error and innerError envelope. The innerError.code reports workload-specific conditions, while the standard OData error.code reports generic conditions. Row-level security runs before lookup, so an out-of-scope tenant resource returns a 404 response instead of a 403 response.

The batchRecordDecisions action returns per-item failures in a 200 OK response, not as HTTP errors.

Related content

• spendingPolicy resource type
• costManagementUserBalance resource type
• creditRequest resource type
• costManagementUsageReportRoot resource type
• costManagementUserUsageRecord resource type