Get aggregated usage

Returns aggregated usage for a single metric over a configurable date range and granularity. This is the recommended endpoint for consuming Usage API data — it replaces the legacy `organization_periodic_usages` and `space_periodic_usages` endpoints (see the [Usage migration guide](/references/content-management-api/usage-migration-guide)). One request returns one metric. To fetch multiple metrics, issue one call per `metric_key`. ### Available metrics Pass one of the following as `metric_key`: | `metric_key` | What it counts | |--------------------------|----------------------------------------------------------| | `api_call_cma` | Content Management API requests | | `api_call_cda` | Content Delivery API requests | | `api_call_cpa` | Content Preview API requests | | `api_call_graphql` | GraphQL API requests | | `api_call_total` | Total API requests across CMA, CDA, CPA, and GraphQL | | `functions_invocations` | Contentful Functions invocations | | `asset_bandwidth` | Asset bandwidth served | | `ai_action_invocation` | AI Action invocations | | `ai_action_word_count` | Words processed by AI Actions | | `ai_consumption_unit` | AI consumption units | | `monthly_active_profiles`| Distinct Personalization profiles matched against a rule in the calendar month | ### Supported dimensions per metric Each metric supports a fixed set of dimensions that you can use in `group`, `filter`, and `order`. Dimension keys use the fully qualified form `sys.dimensions.<name>.sys.<suffix>` everywhere — including `order`, where you prefix `-` for descending (e.g. `order=-sys.dimensions.space.sys.id`). The synthetic column `total_usage` is a bare token (`order=total_usage`, `order=-total_usage`) and is only valid in `order`. | `metric_key` | Allowed dimensions | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | `api_call_cma` | `sys.dimensions.space.sys.id` | | `api_call_cda` | `sys.dimensions.space.sys.id` | | `api_call_cpa` | `sys.dimensions.space.sys.id` | | `api_call_graphql` | `sys.dimensions.space.sys.id` | | `api_call_total` | `sys.dimensions.space.sys.id` | | `functions_invocations` | `sys.dimensions.space.sys.id`, `sys.dimensions.app.sys.id`, `sys.dimensions.function.sys.id` | | `asset_bandwidth` | `sys.dimensions.space.sys.id`, `sys.dimensions.asset.sys.id` | | `ai_action_invocation` | `sys.dimensions.space.sys.id`, `sys.dimensions.ai_action.sys.id`, `sys.dimensions.model.sys.provider`, `sys.dimensions.model.sys.id` | | `ai_action_word_count` | `sys.dimensions.space.sys.id`, `sys.dimensions.ai_action.sys.id`, `sys.dimensions.model.sys.provider`, `sys.dimensions.model.sys.id` | | `ai_consumption_unit` | `sys.dimensions.space.sys.id`, `sys.dimensions.ai_action.sys.id`, `sys.dimensions.model.sys.provider`, `sys.dimensions.model.sys.id` | | `monthly_active_profiles`| None — organization-wide only. `group` and `filter` are not supported for this metric. | Multi-value filters take the `[in]` suffix (up to 10 ids), e.g. `filter[sys.dimensions.space.sys.id][in]=id1,id2`. ### Space coverage `api_call_total` covers every space in your organization, including spaces that made no API calls in the requested period — those report `0`. Sorting descending by total (`order=-total_usage`) lists them last, and `total` in the response is the number of spaces in your organization. The per-API metrics (`api_call_cma`, `api_call_cda`, `api_call_cpa`, and `api_call_graphql`) only cover spaces that recorded usage for that specific API. ### Date range `date[gte]` and `date[lte]` are required and accept `yyyy-mm-dd` or full ISO-8601 date-time. **The API only serves data from the last 12 months** — `date[gte]` cannot be more than 12 months before the current day, irrespective of the requested `granularity`. The `granularity` parameter controls bucket size: `P1D` (daily; max 31-day query window) or `P1M` (monthly; max 12 calendar months including the current month). Default is `P1D`. ### Data freshness Every response includes a top-level `dataLastUpdatedAt` field — an ISO-8601 timestamp of the most recent successful data import covering the returned rows. It is `null` when no data has been imported yet for the requested window (for example, `items` is empty). ### Monthly active profiles `monthly_active_profiles` counts distinct Personalization profiles matched against a personalization rule within a **calendar month**. It is set cardinality, not a sum of daily counts — nothing is excluded, including bot traffic, and merged profiles only take effect the month after the merge. A few things that only apply to this metric: - **Calendar month only.** Query with `granularity=P1M`. `granularity=P1D` is not meaningful for this metric — there is no daily breakdown to return. - **No dimensions.** `monthly_active_profiles` is organization-wide; `group` and `filter` are not supported. - **History starts January 2026.** Months before that with no recorded usage report `0`, not a gap, as long as the organization has at least one month of data within the queried window. An organization with **no** MAPs data at all for the entire window returns an empty `items` array instead. - **Not billing-period aligned.** The metric always reports calendar months and cannot be re-windowed to a custom billing period — MAPs is set cardinality, so a billing-period figure cannot be derived from this dataset. <Info>**NOTE:** Monthly Active Profiles are currently subject to a soft limit. If your usage exceeds your annual included quota, you won't be charged extra automatically. Your services stay active, and our team will reach out to discuss options for your plan.</Info> Available to Organization Admins and Organization Owners.