Skip to navigation
Content Management APIUsage

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).

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_keyWhat it counts
api_call_cmaContent Management API requests
api_call_cdaContent Delivery API requests
api_call_cpaContent Preview API requests
api_call_graphqlGraphQL API requests
api_call_totalTotal API requests across CMA, CDA, CPA, and GraphQL
functions_invocationsContentful Functions invocations
asset_bandwidthAsset bandwidth served
ai_action_invocationAI Action invocations
ai_action_word_countWords processed by AI Actions
ai_consumption_unitAI consumption units
monthly_active_profilesDistinct 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_keyAllowed dimensions
api_call_cmasys.dimensions.space.sys.id
api_call_cdasys.dimensions.space.sys.id
api_call_cpasys.dimensions.space.sys.id
api_call_graphqlsys.dimensions.space.sys.id
api_call_totalsys.dimensions.space.sys.id
functions_invocationssys.dimensions.space.sys.id, sys.dimensions.app.sys.id, sys.dimensions.function.sys.id
asset_bandwidthsys.dimensions.space.sys.id, sys.dimensions.asset.sys.id
ai_action_invocationsys.dimensions.space.sys.id, sys.dimensions.ai_action.sys.id, sys.dimensions.model.sys.provider, sys.dimensions.model.sys.id
ai_action_word_countsys.dimensions.space.sys.id, sys.dimensions.ai_action.sys.id, sys.dimensions.model.sys.provider, sys.dimensions.model.sys.id
ai_consumption_unitsys.dimensions.space.sys.id, sys.dimensions.ai_action.sys.id, sys.dimensions.model.sys.provider, sys.dimensions.model.sys.id
monthly_active_profilesNone — 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.
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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

organization_idstringRequired
Id of organization
metric_keyenumRequired
The metric to query. One metric per request.

Query parameters

date[gte]stringRequiredformat: "date"

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]stringRequiredformat: "date"

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.

granularityenumOptional

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:
groupstringOptional

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]stringOptional

Restrict results to a single space. Use filter[sys.dimensions.space.sys.id][in]=<id1>,<id2> (up to 10 ids) to restrict to a set of spaces. Other dimension filters follow the same pattern (filter[sys.dimensions.<dimension>.sys.id]).

Response headers

Content-TypestringOptional

Content-Type

Response

OK - Request successful