Tenants

The tenant interface consists of the following parts:

Resource	Description
Tenant collection	Retrieves tenants Accessible by url `/tenant/tenants`
Tenant	Represents an individual tenant that can be viewed Accessible by url `/tenant/tenants/<tenantId>`
Application reference collection	Retrieves applications Accessible by url `/tenant/tenants/<tenantId>/applications`
Application reference	Represents an individual application reference that can be viewed Accessible by url `/tenant/tenants/<tenantId>/applications/<applicationId>`
Option collection	Enables creating new options and viewing existing ones Accessible by url `/tenant/options`
Option	Represents an individual option that can be viewed and modified Accessible by url `/tenant/options/<optionCategory>/<optionKey>`
Usage statistics	Returns information on the request load and database usage of tenants
Current tenant	Represents user data for the current logged service user

Important: For all PUT/POST requests, the “Accept” header shall be provided, otherwise an empty response body will be returned.

Tenant ID and tenant domain

The tenant ID is a unique identifier across all tenants in Cumulocity IoT, e.g. t07007007. It cannot be changed after tenant creation.

It is recommended to use auto-generated tenant IDs, which follow the format t<number>, for all tenant types.

The location where a tenant can be accessed is called tenant domain, e.g. mytenant.cumulocity.com. It needs to be unique across all tenants and it can be changed after tenant creation.

The tenant domain may contain lowercase letters, digits or hyphens. It must start with a letter; hyphens are only allowed in the middle; minimum is 2 characters. Note that the usage of underscore characters is deprecated but still possible for backward compatibility reasons.

In general, the tenant domain should be used for communication if it is known.

Important: For support user access, the tenant ID must be used and not the tenant domain.

See Tenant > Current tenant for information on how to retrieve the tenant ID and domain of the current tenant via the API.

In the UI, the tenant ID is displayed in the user dropdown menu, see Getting started > User options and settings in the User guide.

Tenant collection

TenantCollection [application/vnd.com.nsn.cumulocity.tenantCollection+json]

Name	Type	Occurs	Description
self	string	1	A URI linking to this resource.
tenants	array	0..n	List of tenants, see below.
statistics	PagingStatistics	1	Information about paging statistics.
prev	string	0..1	A URI linking to a potential previous page of tenants.
next	string	0..1	A URI linking to a potential next page of tenants.

GET a representation of a Tenant Collection.

Response body: TenantCollection

Required role: ROLE_TENANT_MANAGEMENT_READ

Example Request: Get tenants as sample_tenant.

GET /tenant/tenants
Host: ...
Authorization: Basic ...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantCollection+json;ver=...
Content-Length: ...
{
    "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 1
    },
    "self": "<<Collection URL>>",
    "tenants": [
        {
            "adminName": "admin",
            "allowCreateTenants": false,
            "storageLimitPerDevice": 10485760,
            "applications": {
                "references": [],
                "self":"<<ApplicationCollection of This Tenant  URL>>",
            },
            "company": "sample_company",
            "domain": "sample_domain.com",
            "id": "sample_tenant",
            "ownedApplications": {
                "references": [
                    {
                        "application": {
                            "availability": "PRIVATE",
                            "id": "5",
                            "key": "<<hashed value>>",
                            "name": "sample_private_application",
                            "owner": {
                                "self":"<<Application Owner Tenant URL>>",
                                "tenant": {
                                    "id": "sample_tenant"
                                }
                            },
                            "self":"<<Application 5 URL>>",
                            "type": "EXTERNAL"
                        },
                        "self":"<<This Tenant Application 5 URL>>",
                    },
                    ...
                ],
                "self":"<<ApplicationCollection of This Tenant URL>>",
            },
            "self":"<<This Tenant URL>>",
    "parent": "parentTenant",
            "status": "ACTIVE"
        },
        {
            "applications": {
                "references": [],
                "self": "<<ApplicationCollection of This Tenant URL>>",
            },
            "company": "sample_company",
            "domain": "sample_domain.com",
            "id": "next_sample_tenant",
            "ownedApplications": {
                "references": [
                    {
                        "application": {
                            "availability": "MARKET",
                            "id": "6",
                            "key": "<<hashed value>>",
                            "name": "market_application",
                            "owner": {
                                "self":"<<Application Owner Tenant URL>>",
                                "tenant": {
                                    "id": "next_sample_tenant"
                                }
                            },
                            "self":"<<Application 6 URL>>",
                            "type": "EXTERNAL"
                        },
                        "self":"<<This Tenant Application 6 URL>>",
                    }
                ],
                "self":"<<ApplicationCollection of This Tenant URL>>",
            },
            "self":"<<This Tenant URL>>",
        },
        ...
    ]
}

POST - Create a new Tenant

Request body: Tenant

Response body: Tenant

Required role: ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_CREATE

Example request:

POST /tenant/tenants
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver...

{
    "id" : "sample_tenant",
    "company" : "sample_company",
    "domain" : "sample_domain.com",
    "contactName" : "Mr. Doe",
    "contactPhone" : "0123-4567829",
    "adminEmail" : "john.doe@sample_domain.com",
    "adminName" : "firstAdmin",
    "adminPass" : "myPassword",
    "customProperties" : {"referenceId":"1234567890"},
    "sendPasswordResetEmail": true
}

Example Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Length: ...
Location: <<URL of new tenant>>

{
    "id" : "sample_tenant",
    "allowCreateTenants": false,
    "self" : "<<URL of new tenant>>",
    "company" : "sample_company",
    "domain" : "tenant_nsn.com",
    "contactName" : "Mr. Doe",
    "contactPhone" : "0123-4567829",
    "status" : "ACTIVE",
    "adminName" : "firstAdmin",
    "parent": "parentTenant",
    "customProperties" : {"referenceId":"1234567890"}
}

The following table lists the fields of a tenant creation requests, along with their length constraints. The fragments domain and company always have to be provided.

Field	Description	Max. Length	Required
company	Company name	256	Yes
domain	Domain name to be used for the tenant	256	Yes
id	The tenant ID. Will be auto-generated if not present.	32	No
adminName	Username of the tenant administrator	50	No
adminPass	Password of the tenant administrator	32	No
adminEmail	Email address of the administrator	254	No
contactName	A contact name, for example an administrator, of the tenant	No
contact_phone	20	An international contact phone number	No
customProperties		A set of custom properties of the agent	No

The naming convention for tenant ID is:

only lowercase letters, digits, hyphen and underscore is allowed
MUST start with a letter
hyphen and underscore are only allowed in the middle
MUST have a minimum length of two characters

Tenant

Tenant [application/vnd.com.nsn.cumulocity.tenant+json]

Name	Type	Occurs	Description	Visibility
self	string	0..1	A URI linking to this resource.	Public
id	string: max length="32”	1	Unique identifier of the tenant.	Public
status	string	1	Status of the tenant. Possible values: ACTIVE, SUSPENDED	Private
adminName	string: max length = “50”	1	Administrator user name. Whitespaces, slashes, +$: characters not allowed.	Private
adminEmail	string	1	Administrator Email.	Private
allowCreateTenants	boolean	1	Can this tenant create its own tenants.	Private
storageLimitPerDevice	int	1	Storage quota per device the user has.	Private
adminPassword	string	1	Administrator Password.	Private
sendPasswordResetEmail	boolean	1	Enable password reset.	Private
domain	string: max length = “256”	1	URL of tenants domain.	Public
company	string: max length = “256”	1	Tenants company name.	Public
contactName	string: max length = “30”	1	Contact person name.	Public
contactPhone	string: max length= “20”	1	Contact person phone number.	Public
applications	ApplicationReferenceCollection	1	Collection of tenant subscribed, applications.	Private
ownedApplications	ApplicationReferenceCollection	1	Collection of tenant owned, applications.	Public - only applications with availability MARKET
customProperties	Object	1	Keeps a list of custom properties.	optional
parent	string	1	Name of parent tenant, the creator of this tenant.	Public

Current tenant

Content-Type: application/vnd.com.nsn.cumulocity.currentTenant+json

Field Name	Type	Occurs	Description
name	string	1	Tenant.
domainName	string	1	Domain name.
allowCreateTenants	boolean	1	Flag indicating if a tenant can create subtenants.

GET the current tenant details

Request for the currently logged service user’s tenant.

Required role: ROLE_USER_MANAGEMENT_OWN_READ, or ROLE_SYSTEM

ResponseBody: CurrentTenant

GET /tenant/currentTenant
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: application/vnd.com.nsn.cumulocity.currentTenant+json;;ver=...

Example response:

{
    "allowCreateTenants": true,
    "customProperties": {},
    "domainName": "...",
    "name": "..."  
}

Note that in this case the response property "name" is the actual tenant ID.

GET a representation of a Tenant.

Response body: Tenant

Required role: ROLE_TENANT_MANAGEMENT_READ

Example Request: Get single tenant.

GET /tenant/tenants/<<tenantId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.tenant+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Length: ...
{
    "adminName": "admin",
    "applications": {
        "references": [],
        "self":"<<ApplicationCollection of This Tenant  URL>>",
    },
    "company": "sample_company",
    "domain": "sample_domain.com",
    "allowCreateTenants": false,
    "storageLimitPerDevice": 10485760,
    "id": "sample_tenant",
    "ownedApplications": {
        "references": [
            {
                "application": {
                    "availability": "PRIVATE",
                    "id": "5",
                    "key": "<<hashed value>>",
                    "name": "sample_private_application",
                    "owner": {
                        "self":"<<Application Owner Tenant URL>>",
                        "tenant": {
                            "id": "sample_tenant"
                        }
                    },
                    "self":"<<Application 5 URL>>",
                    "type": "EXTERNAL"
                },
                "self":"<<This Tenant Application 5 URL>>",
            },
           ...
        ],
        "self":"<<ApplicationCollection of This Tenant URL>>",
    },
    "self":"<<This Tenant URL>>",
"parent": "parentTenant",
    "status": "ACTIVE"
}

PUT - Update an existing tenant.

Request body: Tenant

Response body: Tenant

Required role: ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_UPDATE

Example Request :

PUT /tenant/tenants/<<tenantId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Accept: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...

{
   "adminName" : "newAdmin"
}

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Length: ...
{
     "id": "sample_tenant",
     "self":"<<ApplicationCollection of This Tenant URL>>",
    "company": "sample_company",
    "domain": "sample_domain.com",
    "status": "ACTIVE",
    "self":"<<This Tenant URL>>",
    "allowCreateTenants": false,
    "storageLimitPerDevice": 10485760,
    "parent": "parentTenant",
    "ownedApplications": {
        "references": [
            {
                "application": {
                    "availability": "PRIVATE",
                    "id": "5",
                    "key": "<<hashed value>>",
                    "name": "sample_private_application",
                    "owner": {
                        "self":"<<Application Owner Tenant URL>>",
                        "tenant": {
                            "id": "sample_tenant"
                        }
                    },
                    "self":"<<Application 5 URL>>",
                    "type": "EXTERNAL"
                },
                "self":"<<This Tenant Application 5 URL>>",
            },
           ...
        ],
    },
  "adminName" : "newAdmin"
}

Note that updating adminPass and adminEmail updates these settings in the admin user of the tenant. Updating adminName has no effect.

DELETE a representation of a Tenant.

Important: Deleting a subtenant cannot be reverted. For security reasons, it is therefore only available in the management tenant. You cannot delete tenants from any tenant but the management tenant.

Administrators in Enterprise Tenants are only allowed to suspend active subtenants, but not to delete them.

Request body: N/A

Response body: N/A

Required role: ROLE_TENANT_MANAGEMENT_ADMIN

Example request:

DELETE /tenant/tenants/<<tenantId>>
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1  204 NO CONTENT

Application reference collection

ApplicationReferenceCollection [application/vnd.com.nsn.cumulocity.applicationReferenceCollection+json].

Name	Type	Occurs	Description
self	string	1	A URI linking to this resource.
references	array	0..n	List of Options, see below.
statistics	PagingStatistics	1	Information about paging statistics.
prev	string	0..1	A URI linking to a potential previous page of options.
next	string	0..1	A URI linking to a potential next page of options.

POST application to tenant applications

Example Request: Adds application reference to tenant’s applications.

Required role: ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_UPDATE

POST /tenant/tenants/<<tenantId>>/applications
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.applicationReference+json;ver=...
{
    "application":{"self":"<<Application URL>>"}
}

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationReference+json;ver=...
Content-Length: ...
{
    "application":{"self":"<<Application URL>>", "id":...}
}

GET a representation of a ApplicationReferenceCollection.

Response body: ApplicationReferenceCollection

Required role: ROLE_TENANT_MANAGEMENT_READ

Example Request: Get Application reference collection.

GET /tenant/tenants/<<tenantId>>/applications
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.applicationReferenceCollection+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationReferenceCollection+json;ver=...
Content-Length: ...
{
  "self" : "<<Collection URL>>",
  "references": [
    {
      "application": {
          "availability": "PRIVATE",
          "id": "5",
          "key": "<<hashed value>>",
          "name": "sample_private_application",
          "owner": {
              "self":"<<Application Owner Tenant URL>>",
              "tenant": {
                  "id": "sample_tenant"
              }
          },
          "self":"<<Application 5 URL>>",
          "type": "EXTERNAL"
      },
      "self":"<<This Tenant Application 5 URL>>",
    },
        ...
  ],
  "statistics" : {
    "totalPages" : 1,
    "pageSize" : 5,
    "currentPage" : 1
  },
  "next" : "...",
  "prev" : "..."
}

Application reference

ApplicationReference [application/vnd.com.nsn.cumulocity.applicationReference+json].

Name	Type	Occurs	Description
self	string	1	A URI linking to this resource.
reference	Application	0..n	The Application being referenced.

DELETE application reference from tenant’s applications.

Response body: ApplicationReference

Required role: ROLE_TENANT_MANAGEMENT_ADMIN

Example Request: Delete reference.

DELETE /tenant/tenants/<<tenantId>>/applications/<<applicationId>>
Host: ...
Authorization: Basic ...

Example Response :

HTTP/1.1  204 NO CONTENT

Option collection

OptionCollection [application/vnd.com.nsn.cumulocity.optionCollection+json].

Name	Type	Occurs	Description
self	string	1	A URI linking to this resource.
options	array	0..n	List of Options, see below.
statistics	PagingStatistics	1	Information about paging statistics.
prev	string	0..1	A URI linking to a potential previous page of options.
next	string	0..1	A URI linking to a potential next page of options.

GET a representation of a OptionCollection.

Response body: OptionCollection

Required role: ROLE_OPTION_MANAGEMENT_READ

Example Request: Get options.

GET /tenant/options
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
Content-Length: ...
{
  "self" : "<<Collection URL>>",
  "options": [
        {
            "category": "access.control",
            "key": "allow.origin",
            "self": "<<Option access.control.allow.origin URL>>",
            "value": "*"
        },
        ...
  ],
  "statistics" : {
    "totalPages" : 1,
    "pageSize" : 5,
    "currentPage" : 1
  },
  "next" : "...",
  "prev" : "..."
}

POST a representation of a Option.

Request body: Option

Response body: Option

Required role: ROLE_OPTION_MANAGEMENT_ADMIN

Example Request: Post option.

POST /tenant/options
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
    "category" : "alarm.type.mapping",
    "key": "temp_too_high",
    "value": "CRITICAL|temperature too high"
}

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Content-Length: ...
{
    "self" : "<<Option alarm.type.mapping.temp_too_high URL>>"
    "category" : "alarm.type.mapping",
    "key": "temp_too_high",
    "value": "CRITICAL|temperature too high"
}

Option

Options are category-key-value tuples, storing tenant configuration. Some categories of options allow creation of new one, other are limited to predefined set of keys.

Any option of any tenant can be defined as “non-editable” by “management” tenant. Afterwards, any PUT or DELETE requests made on that option by the owner tenant, will result in 403 error (Unauthorized).

Default Options

Category	Key	Default value	Only predefined	Description
access.control	allow.origin	*	yes	Comma separated list of domains allowed for execution of CORS. Wildcards are allowed (e.g. *.cumuclocity.com)
alarm.type.mapping	<<alarmType>>		no	Overrides severity and alarm text for the alarm with type “<<alarmType>>". Severity and text are specified as “<<alarmSeverity>>\|<<alarmText>>". If either part of the text is empty, the value will not be overridden. If severity is “NONE”, the alarm will be suppressed.

Option [application/vnd.com.nsn.cumulocity.option+json]

Name	Type	Occurs	Description
self	string	0..1	A URI linking to this resource.
category	string	1	Category of option.
key	string	1	Key of option.
value	string	1	Value of option.

Info: Adding “credentials.” prefix to the key will make the value of the option to be encrypted. Additionally, when the option is being sent to the microservice, the “credentials.” prefix is removed and the value is decrypted. For example:

{
    "category": "c8y-tutorial-7",
    "key": "credentials.mykey",
    "value": "myvalue"
}

In the request now there will be an additional header:

    "Mykey": "myvalue"

GET a representation of a Option.

Response body: Option

Required role: ROLE_OPTION_MANAGEMENT_READ Example Request: Get single option.

GET /tenant/options/<<category>>/<<key>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
Content-Length: ...
{
    "category": "access.control",
    "key": "allow.origin",
    "self": "<<Option access.control.allow.origin URL>>",
    "value": "*"
}

PUT - Update a Option.

Request body: Option

Response body: Option

Required role: ROLE_OPTION_MANAGEMENT_ADMIN Example Request: Update access.control.allow.origin option.

PUT /tenant/options/<<category>>/<<key>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
    "value": "http://developer.cumulocity.com"
}

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Content-Length: ...
{
    "category": "access.control",
    "key": "allow.origin",
    "self": "<<Option access.control.allow.origin URL>>",
    "value": "http://developer.cumulocity.com"
}

PUT - Update multiple options in provided category

Request body: Option

Response body: Option

Required role: ROLE_OPTION_MANAGEMENT_ADMIN Example Request: Update options in provided category.

PUT /tenant/options/<<category>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
    "key1": "value1",
    "key2": "value2",
    "key3": "value3",
    "key4": "value4"
}

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...

GET Options from provided category.

Response body: Option

Required role: ROLE_OPTION_MANAGEMENT_READ Example Request: Get options from given category.

GET /tenant/options/<<category>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
Content-Length: ...
 {
   "key1": "value1"
   "key2": "value2",
   "key3": "value3",
   "key4": "value4",
 }

PUT - Define option editability.

Request body: Option

Response body: Option

Required role: ROLE_OPTION_MANAGEMENT_ADMIN, Required tenant: management Example Request: Update access.control.allow.origin option.

PUT /tenant/options/<<category>>/<<key>>/editable
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...
{
    "editable": "false"
}

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.option+json;ver=...
Content-Length: ...
{
    "category": "access.control",
    "key": "allow.origin",
    "self": "<<Option access.control.allow.origin URL>>",
    "value": "http://developer.cumulocity.com"
}

System options

This endpoint provides a set of read-only properties pre-defined in platform configuration. The response format is exactly the same as for OptionCollection.

Response body: OptionCollection

Required role: ROLE_OPTION_MANAGEMENT_READ

Example Request: Get system options.

GET /tenant/system/options
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
Content-Length: ...
{
  "options": [
        {
            "category": "access.control",
            "key": "allow.origin",
            "value": "*"
        },
        ...
  ],
}

It is also poss ible to query a single system option by passing category and id in the URL path:

Response body: Option

Required role: ROLE_OPTION_MANAGEMENT_READ Example Request: Get single option.

GET /tenant/system/option/<<category>>/<<id>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.option+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.optionCollection+json;ver=...
Content-Length: ...
{
    "category": "access.control",
    "key": "allow.origin",
    "value": "*"
}

Tenant usage statistics

UsageStatistics

Name	Type	Occurs	Description
day	datetime	1	Date of statistics.
deviceCount	int	1	Number of devices in the tenant (c8y_IsDevice). Latest value for a queried period.
deviceEndpointCount	int	1	Number of devices which do not have child devices (leaf devices). Latest value for a queried period.
deviceRequestCount	int	1	Number of requests that were issued only by devices against the tenant. Sum of all issued requests during the queried period.
deviceWithChildrenCount	int	1	Number of devices with all children. Latest value for a queried period.
requestCount	int	1	Number of requests that were issued against the tenant. Sum of all issued requests during the queried period.
storageSize	int	1	Database storage in use by the tenant, in bytes. Latest value for a queried period.
subscribedApplications	array	1	Names of tenant subscribed applications. Latest value for a queried period.

“requestCount” and “deviceRequestCount” contains the sum of all issued requests during the querying period. “deviceCount” and “storageSize” contain the last reported value during the querying period. Please note:

“requestCount” and “deviceRequestCount” are updated every 5 minutes.
“deviceCount”, “deviceEndpointCount”, “deviceWithChildrenCount”, “storageSize” and “subscribedApplications” are updated daily starting at 23:57.
“storageSize” is affected by your retention rules. It is also affected by the regularly running database optimization functions running in Cumulocity IoT. If the size decreases, it does not necessarily mean that data was deleted.
Days are counted according to server timezone.

“deviceRequestCount” - device requests are recognized as requests that do not contain “X-Cumulocity-Application-Key” header. In addition, requests to /user, /tenant and /application API’s are never counted as “deviceRequestCount”.

Request counting in SmartREST and MQTT:

SmartREST: each row in 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.

Total inbound data transfer

Inbound data transfer refers to the total number of inbound requests performed to transfer data into the Cumulocity IoT platform. This includes sensor readings, alarms, events, commands and alike that are transferred between devices and the Cumulocity IoT platform using the REST and/or MQTT interfaces. Such an inbound request could also originate from a custom microservice, website or any other client.

The table below lists all counters that enhance the Cumulocity IoT tenant statistics and measure the inbound data transfers:

Name	Type	Description
measurementsCreatedCount	int	The number of measurements created. Note: The bulk creation of measurements is handled in a way that each measurement is counted individually.
alarmsCreatedCount	int	The number of alarms created.
alarmsUpdatedCount	int	The number of updates on alarms.
eventsCreatedCount	int	The number of events created.
eventsUpdatedCount	int	The number of updates on events.
inventoriesCreatedCount	int	The number of managed objects created.
inventoriesUpdatedCount	int	The number of updates to managed objects.
totalResourceCreateAndUpdateCount	int	The sum of values above (all inbound transfers).

Info: alarmsCreatedCount increases also when a request is made with valid credentials but missing permissions.

See the table below for more information on how the counters above 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 (e.g. 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 (e.g. status change) in one request	Each alarm creation in a single MQTT request will be counted.	Not supported by C8Y (REST does not support updating multiple alarms in one call).
Creation of an event in one request	One event creation is counted.	One event creation is counted.
Update of an event (e.g. 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 (e.g. 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 (e.g. 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.

TenantUsageStatisticsCollection [application/vnd.com.nsn.cumulocity.tenantUsageStatisticsCollection+json]

Name	Type	Occurs	Description
self	string	1	A URI linking to this resource.
usageStatistics	array	0..n	List of usage statistics, see above.
statistics	object	1	Information about paging statistics.
prev	string	0..1	A URI linking to a potential previous page of tenants.
next	string	0..1	A URI linking to a potential next page of tenants.

GET a representation of a TenantUsageStatisticsCollection

Query param	type
dateFrom	datetime
dateTo	datetime
dateTill (deprecated)	datetime

Response body: TenantUsageStatisticsCollection

Required role: ROLE_TENANT_STATISTICS_READ

Example Request: Get statistics of current tenant starting Aug 1st, 2014, until today.

GET /tenant/statistics?dateFrom=2014-08-01
Host: ...
Authorization: Basic ...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantUsageStatisticsCollection+json; charset=UTF-8; ver=0.9
Content-Length: ...
{
    "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 5
    },
    "self": "<<Collection URL>>",
    "usageStatistics": [ {
        "day": "2014-08-12T00:00:00.000+02:00",
        "deviceCount": 5,
        "deviceEndpointCount": 5,
        "deviceRequestCount": 101966,
        "deviceWithChildrenCount": 5,
        "requestCount": 103966,
        "self": "...",
        "storageSize": 1005442845,
    "subscribedApplications": [
            "testadmin"
        ]
    },
    {
        "day": "2014-08-07T00:00:00.000+02:00",
        "deviceCount": 30,
        "deviceEndpointCount": 15,
        "deviceRequestCount": 114378,
        "deviceWithChildrenCount": 38,
        "requestCount": 116378,
        "self": "...",
        "storageSize": 1151862557,
    "subscribedApplications": [
            "testadmin"
        ]
    },
    ...
    ]
}

GET a summary of all tenant usage statistics

Query param	type
dateFrom	datetime
dateTo	datetime

Response body: application/json

Required role: ROLE_TENANT_MANAGEMENT_READ

Example Request: Get statistics of all tenants starting Aug 1st, 2014, until today.

GET /tenant/statistics/allTenantsSummary?dateFrom=2014-08-01
Host: ...
Authorization: Basic ...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...
[
    {
        "deviceCount": 5,
        "deviceEndpointCount": 5,
        "deviceRequestCount": 114338,
        "deviceWithChildrenCount": 5,
        "requestCount": 116378,
        "tenantId": "tenant1",
        "storageSize": 1151862557,
    "subscribedApplications": [
            "testadmin"
        ]
    },
    {
        "deviceCount": 2,
        "deviceEndpointCount": 2,
        "deviceRequestCount": 114338,
        "deviceWithChildrenCount": 2,
        "requestCount": 116378,
        "tenantId": "tenant2",
        "storageSize": 1151862557,
    "subscribedApplications": [
            "testadmin"
        ]
    },
    ...
]

TenantUsageStatisticsSummary [application/vnd.com.nsn.cumulocity.tenantUsageStatisticsSummary+json]

GET a representation of a TenantUsageStatisticsSummary

Query param	type
dateFrom	datetime
dateTo	datetime
dateTill (deprecated)	datetime

Response body: TenantUsageStatisticsSummary

Required role: ROLE_TENANT_STATISTICS_READ

Example Request: Get summary of requests and database usage from the start of this month until now.

GET /tenant/statistics/summary
Host: ...
Authorization: Basic ...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenantUsageStatisticsSummary+json; charset=UTF-8; ver=0.9
Content-Length: ...

{
    "self": "...",
    "day": "2014-08-21T00:00:00.000+02:00",
    "deviceCount": 30,
    "deviceEndpointCount": 15,
    "deviceRequestCount": 15006838,
    "deviceWithChildrenCount": 38,
    "requestCount": 15013818,
    "storageSize": 983856925,
"subscribedApplications": [
        "testadmin"
    ]
}