Cumulocity

Cumulocity Usage statistics API

Days are counted according to server timezone, so be aware that the tenant usage statistics displaying/filtering may not work correctly when the client is not in the same timezone as the server. However, it is possible to send a request with a time range (using the query parameters `dateFrom` and `dateTo`) in zoned format (for example, `2020-10-26T03:00:00%2B01:00`). Statistics from past days are stored with daily aggregations, which means that for a specific day you get either the statistics for the whole day or none at all. ### Request counting in SmartREST and MQTT * SmartREST: Each row in a SmartREST request is transformed into a separate HTTP request. For example, if one SmartREST request contains 10 rows, then 10 separate calls are executed, meaning that request count is increased by 10. * MQTT: Each row/line counts as a separate request. Creating custom template counts as a single request. ### REST specific counting details * All counters increase also when the request is invalid, for example, wrong payload or missing permissions. * Bulk measurements creation and bulk alarm status update are counted as a single "requestCount"/"deviceRequestCount" and multiple inbound data transfer count. ### SmartREST 1.0 specific counting details * Invalid SmartREST requests are not counted, for example, when the template doesn't exist. * A new template registration is treated as two separate requests. Create a new inventory object which increases "requestCount", "deviceRequestCount" and "inventoriesCreatedCount". There is also a second request which binds the template with X-ID, this increases "requestCount" and "deviceRequestCount". * Each row in a SmartREST request is transformed into a separate HTTP request. For example, if one SmartREST request contains 10 rows, then 10 separate calls are executed, meaning that both "requestCount" and "deviceRequestCount" are increased by 10. ### MQTT specific counting details * Invalid requests are counted, for example, when sending a message with a wrong template ID. * Device creation request and automatic device creation are counted. * Each row/line counts as a separate request. * Creating a custom template counts as a single request, no matter how many rows are sent in the request. * There is one special SmartREST 2.0 template (402 Create location update event with device update) which is doing two things in one call, that is, create a new location event and update the location of the device. It is counted as two separate requests. ### JSON via MQTT specific counting details * Invalid requests are counted, for example, when the message payload is invalid. * Bulk creation requests are counted as a single "requestCount"/"deviceRequestCount" and multiple inbound data transfer count. * Bulk creation requests with a wrong payload are not counted for inbound data transfer count. ### Notifications 2.0 specific counting details * Invalid requests are counted, for example, unsuccessful subscription. * All Notifications 2.0 subscription API requests are counted. * All Notifications 2.0 token API requests are counted. * Notifications 2.0 WebSocket consumer connection requests are not counted. * Messages delivered over Notifications 2.0 WebSocket connections are not counted. ### Total inbound data transfer Inbound data transfer refers to the total number of inbound requests performed to transfer data into the Cumulocity platform. This includes sensor readings, alarms, events, commands and alike that are transferred between devices and the Cumulocity platform using the REST and/or MQTT interfaces. Such an inbound request could also originate from a custom microservice, website or any other client. See the table below for more information on how the counters are increased. Additionally, it shows how inbound data transfers are handled for both MQTT and REST: | Type of transfer | MQTT counter information | REST counter information | |:-----------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Creation of an **alarm** in one request | One alarm creation is counted. | One alarm creation is counted via REST. | | Update of an **alarm** (for example, status change) | One alarm update is counted. | One alarm update is counted via REST. | | Creation of **multiple alarms** in one request | Each alarm creation in a single MQTT request will be counted. | Not supported by C8Y (REST does not support creating multiple alarms in one call). | | Update of **multiple alarms** (for example, status change) in one request | Each alarm update in a single MQTT request will be counted. | Each alarm that matches the filter is counted as an alarm update (causing multiple updates). | | Creation of an **event** in one request | One event creation is counted. | One event creation is counted. | | Update of an **event** (for example, text change) | One event update is counted. | One event update is counted. | | Creation of **multiple events** in one request | Each event creation in a single MQTT request will be counted. | Not supported by C8Y (REST does not support creating multiple events in one call). | | Update of **multiple events** (for example, text change) in one request | Each event update in a single MQTT request will be counted. | Not supported by C8Y (REST does not support updating multiple events in one call). | | Creation of a **measurement** in one request | One measurement creation is counted. | One measurement creation is counted. | | Creation of **multiple measurements** in one request | Each measurement creation in a single MQTT request will be counted. Example: If MQTT is used to report 5 measurements, the measurementCreated counter will be incremented by five. | REST allows multiple measurements to be created by sending multiple measurements in one call. In this case, each measurement sent via REST is counted individually. The call itself is not counted. For example, if somebody sends 5 measurements via REST in one call, the corresponding counter will be increased by 5. Measurements with multiple series are counted as a singular measurement. | | Creation of a **managed object** in one request | One managed object creation is counted. | One managed object creation is counted. | | Update of one **managed object** (for example, status change) | One managed object update is counted. | One managed object update is counted. | | Update of **multiple managed objects** in one request | Each managed object update in a single MQTT request will be counted. | Not supported by C8Y (REST does not support updating multiple managed objects in one call). | | Creation/update of **multiple alarms/measurements/events/inventories** mixed in a single call. | Each MQTT line is processed separately. If it is a creation/update of an event/alarm/measurement/inventory, the corresponding counter is increased by one. | Not supported by the REST API. | | Assign/unassign of **child devices and child assets** in one request | One managed object update is counted. | One managed object update is counted. | | Creation of an **operation** in one request | One operation creation is counted. | One operation creation is counted. | | Update of an **operation** (for example, status change) | One operation update is counted. | One operation update is counted. | ### Microservice usage statistics The microservice usage statistics gathers information on the resource usage for tenants for each subscribed application which are collected on a daily base. The microservice usage's information is stored in the `resources` object. ### Frequently asked questions #### Which requests are counted as general "requestCount"? All requests which the platform receives are counted, including,for example, UI requests, microservices requests, device requests and agents requests. Only a few internal endpoints are not counted: * `/health` (and all endpoints including this URI fragment, like `/tenant/health`) * `/application/currentApplication` (and all subresources, like `/application/currentApplication/subscriptions`) * `/tenant/limit` * `/devicecontrol/deviceCredentials` * `/inventory/templates` (and all subresources) #### My devices are not sending any data, but "requestCount" is increasing, and the total number is really big. Why is this happening? Not only device requests are counted. Every user interaction with UI applications generates some requests to the backend API. Additionally you may have subscribed standard or custom microservices, which also regularly send requests to the platform. Example: If you have four microservices and each microservice sends five requests per minute, this setup creates `4 * 5 * 60 * 24 = 28800` requests per day. Similar numbers arise if there are multiple users working with the given tenant UI concurrently. #### Which requests are counted as "deviceRequestCount"? All requests from "requestCount" except the following: * Tenant API requests * Application API requests * User API requests * Requests with the proper HTTP header `X-Cumulocity-Application-Key`, matching the application key of one of the applications used by a particular tenant The exclusion of the APIs in the list above means that requests to endpoints which start with the mentioned API prefixes are not counted. For example, for the Tenant API the following endpoints are not counted (the list is incomplete): * `/tenant/tenants` * `/tenant/currentTenant` * `/tenant/statistics` * `/tenant/options` > **ⓘ Info:** Each microservice and web application must include the `X-Cumulocity-Application-Key` header in all requests. > Otherwise such requests are counted as device requests which incorrectly affects the "deviceRequestCount" usage metric.

GitHub OpenAPI

Operations 7

GET /tenant/statistics Retrieve statistics of the current tenant #
GET /tenant/statistics/summary Retrieve a usage statistics summary #
GET /tenant/statistics/allTenantsSummary Retrieve a summary of all usage statistics #
POST /tenant/statistics/files Generate a statistics file report #
GET /tenant/statistics/files Retrieve usage statistics files metadata #
GET /tenant/statistics/files/{id} Retrieve a usage statistics file #
GET /tenant/statistics/files/latest/{month} Retrieve the latest usage statistics file #

Documentation

📖
Documentation
https://cumulocity.com/api/core/
📖
Documentation
https://cumulocity.com/docs/concepts/domain-model/
📖
Documentation
https://cumulocity.com/docs/device-integration/device-integration-introduction/
📖
Documentation
https://cumulocity.com/docs/microservice-sdk/
📖
Documentation
https://cumulocity.com/docs/reference/notifications/
📖
Documentation
https://cumulocity.com/api/datahub/
📖
Documentation
https://cumulocity.com/docs/datahub/datahub-overview/
📖
Documentation
https://cumulocity.com/api/dtm/
📖
Documentation
https://cumulocity.com/docs/digital-twin-manager/dtm-overview/
📖
Documentation
https://cumulocity.com/api/edge/
📖
Documentation
https://cumulocity.com/docs/edge/edge-overview/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/openapi/cumulocity-usage-statistics-api-openapi.yml
⚙
AsyncAPI
https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/asyncapi/cumulocity-notification2-asyncapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-managed-object-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-measurement-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-event-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-schema/cumulocity-alarm-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/json-ld/cumulocity-context.jsonld

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/cumulocity:cumulocity-usage-statistics-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cumulocity-usage-statistics-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  version: Latest
  title: Cumulocity Usage statistics API
  x-logo:
    url: https://www.cumulocity.com/docs/images/logo-platform.svg
    backgroundColor: '#F8F8F8'
    altText: Cumulocity
    href: https://www.cumulocity.com/api
  description: '# REST implementation


    This section describes the aspects common to all REST-based interfaces of Cumulocity. The interfaces are based on the Hypertext Transfer Protocol 1.1 using HTTPS. ## HTTP usage


    ### Application management


    Cumulocity uses a so-called "application key" to distinguish requests coming from devices and traffic from applications. If you write an application, pass the following header as part of all requests:


    ```markup

    X-Cumulocity-Application-Key:

    ```


    For example, if you registered your application in the Cumulocity Administration application with the key "myapp", your requests should contain the header:


    ```markup

    X-Cumulocity-Application-Key: myapp

    ```


    This makes your application subscribable and billable. If you implement a device, do not pass the key. > **ⓘ Info:** Make sure that you pass the key in **all** requests coming from an application. If you leave out the key,

    > the request will be considered as a device request, and the corresponding device will be marked as "available". ### Limited HTTP clients


    If you use an HTTP client that can only perform GET and POST methods in HTTP, you can emulate the other methods through an additional "X-HTTP-METHOD" header. Simply issue a POST request and add the header, specifying the actual REST method to be executed. For example, to emulate the "PUT" (modify) method, you can use:


    ```http

    POST ... X-HTTP-METHOD: PUT

    ```


    ### Processing mode


    Every update request (PUT, POST, DELETE) executes with a so-called *processing mode*. The processing modes are as follows:


    |Processing mode|Description|

    |---|---|

    |PERSISTENT (default)|Stores data in the Cumulocity database and sends data to the Streaming Analytics engine. Afterwards, Cumulocity returns the result of the request. This is the default mode.|

    |TRANSIENT|Sends data to the Streaming Analytics engine and immediately returns the results asynchronously but does not store data in Cumulocity’s database. This mode saves storage and processing costs and is useful for example when tracking devices in real time without requiring data to be stored.|

    |QUIESCENT|Behaves similar to the persistent mode with the exception that no real-time notifications will be sent.|

    |CEP|Behaves like the transient mode with the exception that no real-time notifications are sent.|


    To explicitly control the processing mode of an update request, you can use the "X-Cumulocity-Processing-Mode" header with a value of either "PERSISTENT", "TRANSIENT", "QUIESCENT" or "CEP":


    ```markup

    X-Cumulocity-Processing-Mode: PERSISTENT

    ```


    > **ⓘ Info:** Events are always delivered to CEP/Apama for all processing modes. This is independent from real-time notifications. ### Authorization


    All requests issued to Cumulocity are subject to authorization. To determine the required permissions, see the "Required role" entries for the individual requests. To learn more about the different permissions and the concept of ownership in Cumulocity, see Getting started > Technical concepts > Security aspects > Access control > Managing roles and assigning permissions in the Cumulocity user documentation. > **⚠️ Important:** In the Cumulocity API, each granular permission is identified by a unique “permission” string, which is prefixed with ROLE_ (for example, ROLE_ALARM_READ, ROLE_INVENTORY_ADMIN). Therefore, permissions are frequently referred to as “roles” throughout the API as well as in the configuration files. For example, the microservice manifest includes a requiredRoles field, which actually expects a permission string. See also the Glossary of the Cumulocity user documentation for the usage of the terms “permission” and “role” in the Cumulocity context. ### Media types


    Each type of data is associated with an own media type. The general format of media types is:


    ```markup

    application/vnd.com.nsn.cumulocity.+json;ver=;charset=UTF-8

    ```


    Each media type contains a parameter `ver` indicating the version of the type.'
servers:
- description: Cumulocity tenant
  url: https://<TENANT_DOMAIN>
security:
- Basic: []
- OAI-Secure: []
- SSO: []
- JWT-IAM: []
tags:


# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cumulocity/refs/heads/main/openapi/cumulocity-usage-statistics-api-openapi.yml