Usage
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 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.
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 instead.
Get detailed asset bandwidth usage
Organization usage
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.
Space usage
filter[sys.dimensions.space.sys.id]={spaceId} instead. See the Usage migration guide for details.Query organization usage by space and metric for a given date range.