Usage migration guide

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

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.

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:

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

1
{
2
  "sys": { "type": "Array" },
3
  "total": 1, "skip": 0, "limit": 25,
4
  "items": [
5
    {
6
      "sys": {
7
        "id": "<usage_metric_id>",
8
        "type": "OrganizationPeriodicUsage",
9
        "organization": { "sys": { "id": "<org_id>", "type": "Link", "linkType": "Organization" } }
10
      },
11
      "unitOfMeasure": "apiRequestCount",
12
      "metric": "cma",
13
      "dateRange": { "startAt": "2025-01-01", "endAt": "2025-01-03" },
14
      "usage": 100,
15
      "usagePerDay": { "2025-01-01": 30, "2025-01-02": 30, "2025-01-03": 40 }
16
    }
17
  ]
18
}

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

1
{
2
  "sys": { "type": "Array" },
3
  "total": 1, "skip": 0, "limit": 100,
4
  "items": [
5
    {
6
      "sys": {
7
        "id": "<usage_metric_id>",
8
        "type": "ApiCallCma",
9
        "key": "api_call_cma",
10
        "organization": { "sys": { "id": "<org_id>", "type": "Link", "linkType": "Organization" } },
11
        "unitOfMeasurement": "apiRequestCount",
12
        "dimensions": {},
13
        "accumulation": "integrate"
14
      },
15
      "dateRange": { "start": "2025-01-01", "end": "2025-01-03" },
16
      "granularity": "P1D",
17
      "data": [30, 30, 40]
18
    }
19
  ]
20
}

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.