A valid request URL is required to generate request examples{
"included": 123,
"used": 123,
"period": "<string>",
"usedFraction": 123,
"exhausted": true,
"nearLimit": true,
"metered": true
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "admission_unavailable",
"message": "<string>"
}
}How much copilot you have, and how much is gone
Your organisation’s monthly copilot allowance, what has been spent against it this period, and whether it is gone.
THE ALLOWANCE FOLLOWS THE SUBSCRIPTION, one per subscribed device, summed. A pay-as-you-go purchase includes none, so an organisation holding only those has an allowance of zero, which is a real answer, and one that is exhausted from the first token rather than a bar that never fills.
THE UNIT IS TOKENS and the counts cross the wire so that a client can compute a proportion. What a person is shown is the client’s decision; the counts are here because a bar cannot be drawn without them.
READ metered BEFORE DRAWING ANYTHING. When it is false, used is zero because nothing on this deployment counts copilot use, not because nothing was spent. The two are indistinguishable from the number alone, and a bar drawn from the second one shows a measurement nobody made.
ANY SIGNED-IN PRINCIPAL of the organisation may read it, of either role, for the reason the price list is readable by both: a person who can use copilot should be able to see how much of it is left.
503 WHERE NO ALLOWANCE IS CONFIGURED. Reporting zero would show every customer as exhausted, and inventing a figure here would make this service a second answer to a question the price sheet owns.
Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.
A valid request URL is required to generate request examples{
"included": 123,
"used": 123,
"period": "<string>",
"usedFraction": 123,
"exhausted": true,
"nearLimit": true,
"metered": true
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "admission_unavailable",
"message": "<string>"
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Response
This organisation's allowance and what is left of it.
How much copilot this organisation has, and how much of it is gone.
Your monthly allowance in TOKENS, summed over your live subscription purchases. Zero is a real answer and not a missing one: pay as you go includes no allowance at all, so an organisation holding only pay-as-you-go devices has none.
Spent this period, in TOKENS, input and output together.
The billing month both counts are measured in, as YYYY-MM-DD naming its first day. The same period GET /v1/usage reports device time against, so two bars on one screen cannot disagree about which month it is.
used over included, from 0 to 1 and CLAMPED at 1, because a bar cannot be more than full, and any overshoot is already visible in the two counts. Zero when nothing is included.
The allowance is spent, and copilot drops to command mode. TRUE from the first token for an organisation whose allowance is zero.
Past four fifths of the allowance but not yet spent: the point at which a person is warned.
Whether anything on this deployment actually counts copilot use. FALSE means used is zero because nothing measured it, not because nothing was spent, and a percentage drawn from that zero would be a number nobody observed. It is false on every deployment that serves no copilot.