> 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/developers/docs/_mcp/server.

# Usage migration guide

> **Info**
>
> The legacy **Organization usage** `GET /organizations/{organization_id}/organization_periodic_usages` and **Space usage** `GET /organizations/{organization_id}/space_periodic_usages` endpoints are deprecated. **Sunset: 2027-02-28.** Migrate to [Get aggregated usage](/references/content-management-api/usage/get-usage-aggregated) as soon as possible.

The aggregated Usage API endpoint `GET /organizations/{organization_id}/usages/{metric_key}` can fully replace the legacy periodic-usages endpoints. Legacy endpoints remain live until sunset, after which they will be removed from the docs and eventually decommissioned.

This guide maps the legacy parameters and response shape to the new endpoint.

#### Who should migrate?

Anyone calling `GET /organizations/{organization_id}/organization_periodic_usages` or `GET /organizations/{organization_id}/space_periodic_usages`. If you use the [contentful-management.js](https://github.com/contentful/contentful-management.js) SDK, the corresponding `getUsageForOrganization` / `getUsageForSpace` methods are also deprecated in favor of `getUsageAggregated` (rich client) or `usage.getAggregated` (plain client).

The still-supported static-usage endpoints served by gatekeeper are unaffected by this change.

#### 1. One metric per request (biggest breaking change)

Legacy `metric` was a **CSV query parameter** — one call could return several metrics at once (`?metric=cma,cpa,gql`). The new `metric_key` is a **path parameter, single value, enum-only** — one call returns one metric.

A single legacy call fetching N metrics becomes N calls (in serial or parallel) against the aggregated endpoint.

#### 2. Metric name mapping

The enum values changed. If you were calling the legacy endpoint with `metric=cma`, call the aggregated endpoint at `.../usages/api_call_cma`.

| Legacy `metric` | New `metric_key`   |
| --------------- | ------------------ |
| `cma`           | `api_call_cma`     |
| `cda`           | `api_call_cda`     |
| `cpa`           | `api_call_cpa`     |
| `gql`           | `api_call_graphql` |

The aggregated endpoint also exposes metrics that were never available on the legacy endpoints:

* `functions_invocations`
* `asset_bandwidth`
* `ai_action_invocation`
* `ai_action_word_count`
* `ai_consumption_unit`

#### 3. Date parameters

Legacy `startAt` / `endAt` (`yyyy-mm-dd`) → new `date[gte]` / `date[lte]` (ISO-8601 date-time, though `yyyy-mm-dd` is still accepted). Both parameters are now **required**.

The `dateRange` shorthand does **not** exist on the aggregated endpoint — pass the two `date[...]` parameters explicitly.

| Legacy    | Aggregated  |
| --------- | ----------- |
| `startAt` | `date[gte]` |
| `endAt`   | `date[lte]` |

**Retention window (limitation).** The aggregated endpoint only serves data from the **last 12 months** — `date[gte]` cannot be earlier than 12 months before the current day, irrespective of granularity. The legacy endpoints will happily accept older dates and return empty results; the aggregated endpoint rejects them. If you have workflows that reach further back, snapshot the results while the legacy endpoints are still live.

#### 4. Scope and filtering

* **Organization-scope** — legacy `GET /organizations/{orgId}/organization_periodic_usages` maps to `GET /organizations/{orgId}/usages/{metric_key}` with **no** `filter` parameter.
* **Space-scope** — legacy `GET /organizations/{orgId}/space_periodic_usages` maps to the same endpoint with `filter[sys.dimensions.space.sys.id]={spaceId}`.

To fetch a set of spaces in one call, use the `[in]` suffix (up to 10 ids per call): `filter[sys.dimensions.space.sys.id][in]=id1,id2,id3`.

To retrieve organization-wide totals broken down by space, pass `group=sys.dimensions.space.sys.id` — this groups the response by space without narrowing the scope.

**Supported dimensions per metric.** For the four legacy-equivalent metrics (`api_call_cma`, `api_call_cda`, `api_call_cpa`, `api_call_graphql`), only `sys.dimensions.space.sys.id` is available in `filter`, `group`, and `order` — which matches the legacy endpoints. Other metrics support richer dimensions:

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

Dimension keys use the same fully qualified form in `group`, `filter`, and `order`. In `order`, prefix with `-` for descending (e.g. `order=-sys.dimensions.space.sys.id`). The synthetic `total_usage` column is a bare token (`order=total_usage`, `order=-total_usage`) and is only valid in `order`.

#### 5. Response shape

Legacy responses are a flat, paginated list of per-metric usage rows. The aggregated endpoint returns a **grouped time series** with configurable granularity.

Set `granularity=P1D` for daily buckets (max 31-day window) or `granularity=P1M` for monthly buckets (max 12 months including the current month). Defaults to `P1D`.

**Legacy response (`organization_periodic_usages?metric=cma&startAt=2025-01-01&endAt=2025-01-03`):**

```json
{
  "sys": { "type": "Array" },
  "total": 1, "skip": 0, "limit": 25,
  "items": [
    {
      "sys": {
        "id": "<usage_metric_id>",
        "type": "OrganizationPeriodicUsage",
        "organization": { "sys": { "id": "<org_id>", "type": "Link", "linkType": "Organization" } }
      },
      "unitOfMeasure": "apiRequestCount",
      "metric": "cma",
      "dateRange": { "startAt": "2025-01-01", "endAt": "2025-01-03" },
      "usage": 100,
      "usagePerDay": { "2025-01-01": 30, "2025-01-02": 30, "2025-01-03": 40 }
    }
  ]
}
```

**Aggregated response (`usages/api_call_cma?date[gte]=2025-01-01&date[lte]=2025-01-03&granularity=P1D`):**

```json
{
  "sys": { "type": "Array" },
  "total": 1, "skip": 0, "limit": 100,
  "items": [
    {
      "sys": {
        "id": "<usage_metric_id>",
        "type": "ApiCallCma",
        "key": "api_call_cma",
        "organization": { "sys": { "id": "<org_id>", "type": "Link", "linkType": "Organization" } },
        "unitOfMeasurement": "apiRequestCount",
        "dimensions": {},
        "accumulation": "integrate"
      },
      "dateRange": { "start": "2025-01-01", "end": "2025-01-03" },
      "granularity": "P1D",
      "data": [30, 30, 40]
    }
  ]
}
```

The per-day counts move from the `usagePerDay` object (keyed by date) to a positional `data` array (in date order). The `metric` string is replaced by `sys.key`, and the surrounding dimensions live on `sys.dimensions`.

#### 6. Migration timeline

* Migrate as soon as convenient — the aggregated endpoint is available now.
* Legacy endpoints continue to serve traffic until sunset on **2027-02-28**.
* After sunset, the legacy endpoints are removed from these docs; eventual decommissioning at the service layer is coordinated separately.