> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

Enables users to query organization API usage data.
You can further filter by Contentful API types (cma, cda, cpa, gql) through the
parameter `metric`. Results are paginated and support ordering.

### Permissions

Usage API is available to Premium/Enterprise, Basic and Free plans.
Premium/Enterprise and Basic customers can access historical usage data with API batch size of 45 days. Free plans can access the last 45 days of historical usage data.
Usage API calls can only be made by a user with the Organization Admin or Organization Owner role.

## Aggregated usage

Query usage for a single metric with configurable granularity, date range, and grouping. This is the recommended endpoint for both organization-wide and space-scoped queries. It replaces the legacy `Organization usage` and `Space usage` endpoints below — see the [Usage migration guide](/references/content-management-api/usage-migration-guide) for details.

Pass one `metric_key` per request (for example `api_call_cma`, `functions_invocations`, or `asset_bandwidth`). Use `filter[sys.dimensions.space.sys.id]` to narrow to a space, or `group=sys.dimensions.space.sys.id` to keep organization-wide totals but break the response out per space. Bucket size is controlled by `granularity` — `P1D` for daily (max 31 days), `P1M` for monthly (max 12 months).

Data retention is limited to the last **12 months** — `date[gte]` cannot be earlier than 12 months before the current day, regardless of granularity. See the endpoint reference for the full list of supported metrics and per-metric dimensions.

[Get aggregated usage](/references/content-management-api/usage/get-usage-aggregated)

## Detailed usage

Returns the top 30 assets by bandwidth used for an organization over a given date range, ranked descending and grouped by asset and space. Granularity is fixed to daily (`P1D`); the query window must not exceed 31 days. This is a fixed-shape leaderboard rather than a general-purpose query — for organization-wide totals across other metrics, use the [Get aggregated usage endpoint](/references/content-management-api/usage/get-usage-aggregated) instead.

[Get detailed asset bandwidth usage](/references/content-management-api/usage/get-usage-asset-bandwidth-detailed)

## Organization usage

> **Info**
>
> **Deprecated. Sunset: 2027-02-28.** Use [Aggregated usage](#aggregated-usage) instead. See the [Usage migration guide](/references/content-management-api/usage-migration-guide) for details.

Query organization usage by `metric` for a given date range.
If `startAt` and `endAt` are not passed through the query a historical data for the last 45 days will be returned by default.

[Get organization usage](/references/content-management-api/usage/get-organization-usage)

## Space usage

> **Info**
>
> **Deprecated. Sunset: 2027-02-28.** Use [Aggregated usage](#aggregated-usage) with `filter[sys.dimensions.space.sys.id]={spaceId}` instead. See the [Usage migration guide](/references/content-management-api/usage-migration-guide) for details.

Query organization usage by space and `metric` for a given date range.

[Get space usage](/references/content-management-api/usage/get-space-usage)