Status: Public Preview — behaviour may change. The Graph endpoints are in beta.
What it does
The Microsoft 365 Copilot Cost Management API lets admins govern and observe tenant consumption of Copilot credits through Microsoft Graph, rooted at /copilot/costManagement. You can read the tenant credit balance, create spending policies that cap consumption for an audience, scope a policy to everyone or to selected groups, include or exclude individual AI services, set notify-only threshold alerts, and diagnose a single user's per-service balance.
Key facts
- It's credit-denominated. Currency, invoices, prices and purchase forecasts are deliberately excluded.
- Tenant credit balance is a snapshot with one row per billing method (prepaid credits or pay-as-you-go).
- A spending policy has a period limit and a per-user limit. The period is a UTC calendar month: month-to-date consumption that resets at 00:00 UTC on the first. Both limits are required on create; use an unlimited quantity if you don't want a per-user cap.
- Audience is either every user (
allUsersSpendingPolicy) or selected groups (selectedGroupsSpendingPolicy), with groups managed through reference links. - A new policy is created disabled and becomes enabled once its audience is in place.
- Service settings are keyed by
serviceId(for examplecoworkorworkIQ). There's no DELETE; you exclude a service by setting its state todisabled. A service setting does nothing while the parent policy is disabled or provisioning. - Alerts are notify-only. They can't stop consumption. Configure them after the policy exists: create a disabled alert setting, add recipients, then enable. At least one recipient is needed while alerting is on.
- Permissions are the
CopilotCostManagement-*family, mostly delegated only. The tenant credit balance read also supports theCopilotCostManagement.Read.Allapplication permission. Personal Microsoft accounts aren't supported. - Creating a policy also needs the Billing Administrator or Global Administrator role at runtime.
When to use / skip
Use it when you want spend guardrails as code: a pilot group with a monthly cap, a FinOps report on policies and limits, or a helpdesk script that explains why a user is blocked. Skip it if the admin centre controls already cover the scenario and you have nobody to maintain scripts against a beta API.
Configuration decisions
- All users or selected groups, and who owns the group membership.
- Period and per-user limits, and whether any services should sit outside the policy.
- Alert thresholds (absolute or percentage) and recipients, remembering these only notify.
- Which roles hold read versus read-write permissions.
Gotchas
- A threshold alert is not a cap. If finance expects a hard stop, the limits do that and the alerts don't.
- Because it's beta, shapes can change. Don't build the only copy of your governance process on it.
- Use the policy ETag in
If-Matchfor service-setting changes, otherwise concurrent edits will collide. - Creating a policy with the wrong permissions fails at runtime on the directory role, not only on the Graph scope.
Consultant notes
- Agree the credit model with the client's finance lead before touching the API. Teams routinely turn up wanting per-department chargeback, which this API does not provide.
- A pilot policy for one group with an 80 percent alert is a cheap, good first step. Name a human who reads that alert.
- Helpdesk diagnostics are the sleeper feature. "Why can't Sam use it" is a daily question once agents start consuming credits.
Revisit when the API moves out of beta or gains currency-denominated reporting.