Was this page helpful?

API Usage Insights

Introduction

Contentful provides an organization with the API usage insights (number of API requests) on a daily basis, split over a specified usage period.

These insights help organizations to view the API usage and thereby understand the invoices for exceeding the usage limits. Historical usage details can further enable an organization to compare and analyze the usage with their own traffic tracking reports, understand the overages and what caused the spike.

The daily usage of the APIs (CDA, CMA, CPA, or all the APIs), over a usage period, are provided on the following two levels:

  • organization level; and
  • space level.

Note: The usage insights are not real time and lag by 48 hours. For example, the usage details on 20th October are the reflection of usage till 18th October.

It is possible to view the usage insights on the Web App or with an API call.

Disclaimer

This feature is currently in alpha and is under active development. It may undergo some major changes, hence not recommended to use for production.

Share your thoughts, ideas, and feedback using the feedback button, or connect with us on our #alpha-usage-insights Slack community channel.

Give feedback

Viewing usage insights on the Web App

Pre-requisite

  • Administrative access right to the space.

Getting Started

  1. Navigate to the Organization settings located on the left pane.
  2. Click the Usage tab on the top menu. A dashboard explaining the API usage for the current usage period is displayed.

On this dashboard it is possible to view the total number of API requests and the API requests for CMA, CDA, and CPA for their top 3 spaces.

  1. To view the usage insights for a particular usage period, select the desired usage period from the Usage period drop down on the top right.

Viewing usage insights with an API call

Pre-requisite

  • A valid Content Management API token.

Get organization usage periods

The endpoint on CMA returns usage periods along with start and end date for each usage period.

Note: In the alpha version, the insights are provided for an usage period and not for custom dates. The reason being, usage metrics are reset at the end of every usage period. However, in future there can be a possibility to get insights for custom dates.

Endpoint: [GET] /organizations/:organization_id/usage_periods

Base URL

https://api.contentful.com

Headers

x-contentful-enable-alpha-feature: usage-insights

{
  "total": 3,
  "sys": {
    "type": "Array"
  },
  "items": [
    {
      "sys": {
        "type": "UsagePeriod",
        "id": 3
      },
      "startDate": "2018-07-15T00:00:00.000Z",
      "endDate": null
    },
    {
      "sys": {
        "type": "UsagePeriod",
        "id": 2
      },
      "startDate": "2018-06-15T00:00:00.000Z",
      "endDate": "2018-07-14T00:00:00.000Z"
    },
    {
      "sys": {
        "type": "UsagePeriod",
        "id": 1
      },
      "startDate": "2018-05-15T00:00:00.000Z",
      "endDate": "2018-06-14T00:00:00.000Z"
    }
  ]
}

Get organization resource usage

The endpoint on a CMA returns daily resource usage of an organization or spaces within the organization.

Endpoint: [GET] /organisations/:organisation_id/usages/:type

Base URL

https://api.contentful.com

Headers

x-contentful-enable-alpha-feature: usage-insights

Query parameters

organisation_id: ID of an organization

type: organization or space

filters[metric]: cda or cma or cpa or all_apis

filters[usagePeriod]: {usagePeriod}

orderBy[metricUsage]: asc or desc

skip: no of items to skip

limit no of items to fetch

{
  "total": 2,
  "limit": 2,
  "skip": 0,
  "sys": {
    "type": "array"
  },
  "items": [
    {
      "sys": {
        "type": "ApiUsage",
        "id": "20_1ElgCn1mi1UHSBLTP2v4TD",
        "usagePeriod": {
          "sys": {
            "type": "Link",
            "linkType": "UsagePeriod",
            "id": "20"
          }
        },
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "1ElgCn1mi1UHSBLTP2v4TD"
          }
        }
      },
      "unitOfMeasure": "apiRequests",
      "interval": "daily",
      "startDate": "2018-06-15T00:00:00.000Z",
      "endDate": "2018-07-14T00:00:00.000Z",
      "usage": [6442, 5952, 8713, 1998, 5209, 2894, 1144, 2152, 4305, 4534, 1832, 5979, 6189, 954, 4847, 3953, 9094, 1800, 5044, 1232, 920, 2396, 9551, 4350, 2809, 5496, 9442, 7301, 4349, 1778]
    },
    {
      "sys": {
        "type": "ApiUsage",
        "id": "20_1ElgCn1mi1UHSBLTP2v5TD",
        "usagePeriod": {
          "sys": {
            "type": "Link",
            "linkType": "UsagePeriod",
            "id": "20"
          }
        },
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "1ElgCn1mi1UHSBLTP2v5TD"
          }
        }
      },
      "unitOfMeasure": "apiRequests",
      "interval": "daily",
      "startDate": "2018-06-15T00:00:00.000Z",
      "endDate": "2018-07-14T00:00:00.000Z",
      "usage": [6444, 5955, 8716, 1998, 5209, 2894, 1144, 2152, 4305, 4534, 1832, 5979, 6189, 954, 4847, 3953, 9094, 1800, 5044, 1232, 920, 2396, 9551, 4350, 2809, 5496, 9442, 7301, 4349, 1778]
    }
  ]
}