Get aggregated usage

GET

https://api.contentful.com/organizations/:organization_id/usages/:metric_key

GET

/organizations/:organization_id/usages/:metric_key

$ curl --include \
>      --request GET \
>      --header 'Authorization: Bearer <cma_token>' \
>      "https://api.contentful.com/organizations/<organization_id>/usages/api_call_cma?date%5Bgte%5D=2025-01-01&date%5Blte%5D=2025-01-31&granularity=P1D&group=sys.dimensions.space.sys.id"

200Usage_getUsageAggregated_example

1 {
2   "items": [
3     {
4       "data": [
5         1247,
6         892,
7         1503,
8         1876,
9         2104,
10         1652,
11         1289,
12         1934,
13         2287,
14         1745,
15         1523,
16         1108,
17         987,
18         1456,
19         1823,
20         2145,
21         1967,
22         1734,
23         1512,
24         1289,
25         1678,
26         1945,
27         2214,
28         1876,
29         1543,
30         1287,
31         1098,
32         1456,
33         1732,
34         2087,
35         1876
36       ],
37       "dateRange": {
38         "end": "2025-01-31",
39         "start": "2025-01-01"
40       },
41       "granularity": "P1D",
42       "sys": {
43         "accumulation": "integrate",
44         "dimensions": {
45           "space": {
46             "sys": {
47               "id": "yadj1kx9rmg0",
48               "linkType": "Space",
49               "type": "Link"
50             }
51           }
52         },
53         "id": "<usage_metric_id>",
54         "key": "api_call_cma",
55         "organization": {
56           "sys": {
57             "id": "0D9ZC8rLWiw6x5qizZGiRs",
58             "linkType": "Organization",
59             "type": "Link"
60           }
61         },
62         "type": "ApiCallCma",
63         "unitOfMeasurement": "apiRequestCount"
64       }
65     }
66   ],
67   "limit": 100,
68   "skip": 0,
69   "sys": {
70     "type": "Array"
71   },
72   "total": 2
73 }

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

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`

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.

Available to Organization Admins and Organization Owners.

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 | ### 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` | 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`. 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