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

Example Request

GET /organizations/:organization_id/usage_periods

Example Response

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

Get organization resource usage

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

Endpoint: [GET] /organizations/:organization_id/usages/:type

Base URL

https://api.contentful.com

Headers

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

Query parameters

organization_id: ID of an organization

type: organization or space

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

filters[usagePeriod]: usagePeriod id

orderBy[metricUsage]: asc or desc, defaults to asc which will order the items array of the response according to the number of API requests made for each space. This has no effect when usage type is organization.

skip: number of items to skip, defaults to 0

limit number of items to fetch, defaults to 25

Example Request

GET /organizations/:organization_id/usages/spaces?filters[metric]=all_apis&filters[usagePeriod]=2

Example Response

{
  "total": 2,
  "limit": 25,
  "skip": 0,
  "sys": {
    "type": "array"
  },
  "items": [
    {
      "sys": {
        "type": "ApiUsage",
        "id": "2_yadj1kx9rmg0",
        "usagePeriod": {
          "sys": {
            "type": "Link",
            "linkType": "UsagePeriod",
            "id": "2"
          }
        },
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "yadj1kx9rmg0"
          }
        }
      },
      "unitOfMeasure": "apiRequests",
      "interval": "daily",
      "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": "2_862z8hanwnlk",
        "usagePeriod": {
          "sys": {
            "type": "Link",
            "linkType": "UsagePeriod",
            "id": "2"
          }
        },
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "862z8hanwnlk"
          }
        }
      },
      "unitOfMeasure": "apiRequests",
      "interval": "daily",
      "usage": [1163, 4921, 1502, 4284, 4432, 3291, 1322, 917, 4246, 384, 1316, 1324, 648, 3001, 1859, 2263, 1098, 904, 4933, 133, 4751, 2732, 3219, 768, 84, 1097, 1910, 32, 682, 13]
    }
  ]
}

The numbers in the usage array in the response represent the number of api requests made from 00:00:00 UTC until 23:59:59 UTC for each day starting with the startDate of the usage period. For this example, on 2018-06-15 there were 6,442 requests for space yadj1kx9rmg0 and 1,163 requests for space 862z8hanwnlk and on 2018-06-16 there were 5,952 requests for space yadj1kx9rmg0 and 4,921 requests for 862z8hanwnlk and so on.