> 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/_mcp/server. # Get aggregated usage GET https://api.contentful.com/organizations/{organization_id}/usages/{metric_key} 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 metricsPass 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 metricEach 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..sys.` 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 freshnessEvery 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.**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.Available to Organization Admins and Organization Owners. Reference: https://contentful.com/developers/docs/references/content-management-api/usage/get-usage-aggregated ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `organization_id` (string, required) — Id of organization - `metric_key` (enum, required) — The metric to query. One metric per request. - Allowed values: `api_call_cma`, `api_call_cda`, `api_call_cpa`, `api_call_graphql`, `api_call_total`, `functions_invocations`, `asset_bandwidth`, `ai_action_invocation`, `ai_action_word_count`, `ai_consumption_unit`, `monthly_active_profiles` ### Query parameters - `date[gte]` (string, required) — Start of the query window (inclusive). Accepts `yyyy-mm-dd` or full ISO-8601. Cannot be more than 12 months before the current day — the API only serves data from the last 12 months. - `date[lte]` (string, required) — End of the query window (inclusive). Accepts `yyyy-mm-dd` or full ISO-8601. Maximum window is 31 days for `granularity=P1D` and 12 months (including the current month) for `granularity=P1M`. - `granularity` (enum, optional) — Bucket size in ISO-8601 duration format. `P1D` returns one point per day (max 31-day window). `P1M` returns one point per month (max 12 months). Defaults to `P1D`. - Allowed values: `P1D`, `P1M` - `group` (string, optional) — Comma-separated list of dimension keys to group results by, for example `sys.dimensions.space.sys.id`. When omitted, results are returned aggregated across all dimensions. - `filter[sys.dimensions.space.sys.id]` (string, optional) — Restrict results to a single space. Use `filter[sys.dimensions.space.sys.id][in]=,` (up to 10 ids) to restrict to a set of spaces. Other dimension filters follow the same pattern (`filter[sys.dimensions..sys.id]`). ## Response ### 200 OK - Request successful - `map from string to any` ## Examples ### API calls, daily granularity **Response** ```json { "items": [ { "data": [ 1247, 892, 1503, 1876, 2104, 1652, 1289, 1934, 2287, 1745, 1523, 1108, 987, 1456, 1823, 2145, 1967, 1734, 1512, 1289, 1678, 1945, 2214, 1876, 1543, 1287, 1098, 1456, 1732, 2087, 1876 ], "dataLastUpdatedAt": "2025-02-01T04:12:09.000Z", "dateRange": { "end": "2025-01-31", "start": "2025-01-01" }, "granularity": "P1D", "sys": { "accumulation": "integrate", "dimensions": { "space": { "sys": { "id": "yadj1kx9rmg0", "linkType": "Space", "type": "Link" } } }, "id": "", "key": "api_call_cma", "organization": { "sys": { "id": "0D9ZC8rLWiw6x5qizZGiRs", "linkType": "Organization", "type": "Link" } }, "type": "ApiCallCma", "unitOfMeasurement": "apiRequestCount" } } ], "limit": 100, "skip": 0, "sys": { "type": "Array" }, "total": 2 } ``` **SDK Code** ```android Android SDK currently doesn't implement this endpoint. ``` ```java Java SDK currently doesn't implement this endpoint. ``` ```kotlin Kotlin SDK currently doesn't implement this endpoint. ``` ```swift Swift We currently don't provide a CMA SDK for this platform. ``` ```js-legacy JavaScript (legacy) import { createClient } from 'contentful-management' const client = createClient({ accessToken: '' }, { type: 'legacy' }) client.getUsageAggregated('', 'api_call_cma', { 'date[gte]': '2025-01-01', 'date[lte]': '2025-01-31', granularity: 'P1D', group: 'sys.dimensions.space.sys.id' }) ``` ```javascript JavaScript import { createClient } from 'contentful-management' const client = createClient({ accessToken: '' }) const usage = await client.usage.getAggregated({ organizationId: '', metricKey: 'api_call_cma', query: { 'date[gte]': '2025-01-01', 'date[lte]': '2025-01-31', granularity: 'P1D', group: 'sys.dimensions.space.sys.id' } }) ``` ```php PHP SDK currently doesn't implement this endpoint. ``` ```ruby Ruby SDK currently doesn't implement this endpoint. ``` ```python Python SDK currently doesn't implement this endpoint. ``` ```.net .NET SDK currently doesn't implement this endpoint. ``` ### Monthly active profiles, current month **Response** ```json { "items": [ { "data": [ 12507 ], "dataLastUpdatedAt": "2026-06-12T04:17:33.000Z", "dateRange": { "end": "2026-06-30", "start": "2026-06-01" }, "granularity": "P1M", "sys": { "accumulation": "integrate", "dimensions": {}, "id": "", "key": "monthly_active_profiles", "organization": { "sys": { "id": "0D9ZC8rLWiw6x5qizZGiRs", "linkType": "Organization", "type": "Link" } }, "type": "MonthlyActiveProfile", "unitOfMeasurement": "profiles" } } ], "limit": 100, "skip": 0, "sys": { "type": "Array" }, "total": 1 } ``` **SDK Code** ```android Android SDK currently doesn't implement this endpoint. ``` ```java Java SDK currently doesn't implement this endpoint. ``` ```kotlin Kotlin SDK currently doesn't implement this endpoint. ``` ```swift Swift We currently don't provide a CMA SDK for this platform. ``` ```js-legacy JavaScript (legacy) import { createClient } from 'contentful-management' const client = createClient({ accessToken: '' }, { type: 'legacy' }) client.getUsageAggregated('', 'api_call_cma', { 'date[gte]': '2025-01-01', 'date[lte]': '2025-01-31', granularity: 'P1D', group: 'sys.dimensions.space.sys.id' }) ``` ```javascript JavaScript import { createClient } from 'contentful-management' const client = createClient({ accessToken: '' }) const usage = await client.usage.getAggregated({ organizationId: '', metricKey: 'api_call_cma', query: { 'date[gte]': '2025-01-01', 'date[lte]': '2025-01-31', granularity: 'P1D', group: 'sys.dimensions.space.sys.id' } }) ``` ```php PHP SDK currently doesn't implement this endpoint. ``` ```ruby Ruby SDK currently doesn't implement this endpoint. ``` ```python Python SDK currently doesn't implement this endpoint. ``` ```.net .NET SDK currently doesn't implement this endpoint. ``` ### Monthly active profiles, 12-month trend **Response** ```json { "items": [ { "data": [ 0, 0, 0, 0, 0, 0, 41802, 44190, 46875, 48210, 51002, 12507 ], "dataLastUpdatedAt": "2026-06-12T04:17:33.000Z", "dateRange": { "end": "2026-06-30", "start": "2025-07-01" }, "granularity": "P1M", "sys": { "accumulation": "integrate", "dimensions": {}, "id": "", "key": "monthly_active_profiles", "organization": { "sys": { "id": "0D9ZC8rLWiw6x5qizZGiRs", "linkType": "Organization", "type": "Link" } }, "type": "MonthlyActiveProfile", "unitOfMeasurement": "profiles" } } ], "limit": 100, "skip": 0, "sys": { "type": "Array" }, "total": 1 } ``` **SDK Code** ```android Android SDK currently doesn't implement this endpoint. ``` ```java Java SDK currently doesn't implement this endpoint. ``` ```kotlin Kotlin SDK currently doesn't implement this endpoint. ``` ```swift Swift We currently don't provide a CMA SDK for this platform. ``` ```js-legacy JavaScript (legacy) import { createClient } from 'contentful-management' const client = createClient({ accessToken: '' }, { type: 'legacy' }) client.getUsageAggregated('', 'api_call_cma', { 'date[gte]': '2025-01-01', 'date[lte]': '2025-01-31', granularity: 'P1D', group: 'sys.dimensions.space.sys.id' }) ``` ```javascript JavaScript import { createClient } from 'contentful-management' const client = createClient({ accessToken: '' }) const usage = await client.usage.getAggregated({ organizationId: '', metricKey: 'api_call_cma', query: { 'date[gte]': '2025-01-01', 'date[lte]': '2025-01-31', granularity: 'P1D', group: 'sys.dimensions.space.sys.id' } }) ``` ```php PHP SDK currently doesn't implement this endpoint. ``` ```ruby Ruby SDK currently doesn't implement this endpoint. ``` ```python Python SDK currently doesn't implement this endpoint. ``` ```.net .NET SDK currently doesn't implement this endpoint. ```