---
title: "TinyMCE AI Usage API"
description: "Retrieve the TinyMCE AI credits consumed by an environment and by each of its users over a period, from a back end."
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/tinymceai-usage/"
md_url: "https://www.tiny.cloud/docs/tinymce/latest/tinymceai-usage/index.md"
version: "latest"
last_updated: "2026-11-04T13:52:23Z"
tokens: 549
---
# TinyMCE AI Usage API

The Usage API returns the credits that the TinyMCE AI service recorded for an environment over a period of time. A request can also return the credits for each listed user, or for every user with activity in the period.

The endpoint is `POST /v1/admin/billing/usage`. It is an administration endpoint: back-end code calls it with an administration token. The `tinymceai` plugin does not call it.

## Requirements

- **Deployment**: the Tiny Cloud-hosted TinyMCE AI service. The usage is reported for the environment that the token identifies in its `aud` claim.
- **Token**: a token that grants `ai:admin`, signed and used only on a back end. See [Admin permissions](../tinymceai-permissions/#admin-permissions).

## Get usage

1. Sign an administration token on the back end. Sign it with a JWT signing key of the Tiny Cloud API key, in the same way as user tokens (see [JWT authentication](../tinymceai-jwt-authentication-intro/)), and include `ai:admin` in the permissions.
2. Send `POST /v1/admin/billing/usage` to `https://tinymceai.api.tiny.cloud` with the period to report on. Set `users` to the string `"*"` to report on every user with activity in the period.
3. Read the `environment` object for the environment total, and the `users` array for the credits of each user.

A user ID in the request and the response is the `sub` claim of the tokens of that user.

For the request and response fields and the error codes, see [Get billing usage](https://tinymceai.api.tiny.cloud/v1/docs#tag/Billing/operation/getBillingUsage) in the API reference. Errors use the body described in [Error responses](../tinymceai-api-overview/#error-responses).

## Related features

- [Admin permissions](../tinymceai-permissions/#admin-permissions): The `ai:admin` permission and how to handle administration tokens.
- [JWT authentication](../tinymceai-jwt-authentication-intro/): Token claims, including `aud` and `sub`.
- [Limits](../tinymceai-limits/): Rate limits, context limits, and file limits.
- [API overview](../tinymceai-api-overview/): The features of the TinyMCE AI REST API and the conventions they share.
- [Billing API](https://tinymceai.api.tiny.cloud/v1/docs#tag/Billing): Request and response schemas, and error codes.