usage.report

The usage.report command gets a billing report for the specified organization.

Requires Org Admin rights.

TR50 Request

{
  "cmd": {
    "command": "usage.report",
    "params": {
      "orgKey": "DEV",
      "start": "202-12-01T00:00:00Z",
      "end": "2021-12-31T23:59:59Z",
      "includeSubOrgs": true
    }
  }
}

Request Parameters

Name Type Required Description
orgKey String The key of the organization. Defaults to the current org.
start String Yes The timestamp representing the beginning of the billing period.
end String The timestamp representing the end of the billing period.
includeSubOrgs Bool Indicates that the response should also contain sub organization records. Defaults to false.
includeCountsByThingDef Bool   Indicates if the report should include a list of the total number of things and billable things per thing definition.
includeCountsByType Array   Array of Thing counts by type. Various Thing types includes: gateway, lwm2m, lora, and generic.

TR50 Response

If the command is sent successfully a success message and the results are returned. Otherwise, an error and error message will be returned.

{
    "cmd": {
        "success": true,
        "params": {
            "header": {
                "customerRefId": "ABCDEF012345",
                "end": "2021-12-31T23:59:59Z",
                "orgId": "534c36e53100460721000051",
                "orgKey": "DEV",
                "orgName": "Development",
                "start": "2019-12-01T00:00:00Z"
            },
            "report": [
                {
                    "orgKey": "DEV",
                    "customerRefId": "ABCDEF012345",
                    "parentOrgKey": "",
                    "countBillableThings": 10,
                    "countThings": 31,
                    "countConnections": 116,
                    "countApiCalls": 1952043,
                    "countStorage": 50513072128
                },
                {
                    "orgKey": "SUBORG2",
                    "customerRefId": "",
                    "parentOrgKey": "DEV",
                    "countBillableThings": 0,
                    "countThings": 1,
                    "countConnections": 0,
                    "countApiCalls": 107,
                    "countStorage": 21680128
                },
                {
                    "orgKey": "SUBORG3",
                    "customerRefId": "",
                    "parentOrgKey": "DEV",
                    "countBillableThings": 0,
                    "countThings": 1,
                    "countConnections": 0,
                    "countApiCalls": 102,
                    "countStorage": 22704128
                },
                {
                    "orgKey": "SUBORG4",
                    "customerRefId": "",
                    "parentOrgKey": "DEV",
                    "countBillableThings": 0,
                    "countThings": 0,
                    "countConnections": 0,
                    "countApiCalls": 146,
                    "countStorage": 17342464
                },
                {
                    "orgKey": "FUSION",
                    "customerRefId": "LMNOPQ345678",
                    "parentOrgKey": "DEV",
                    "countBillableThings": 0,
                    "countThings": 3,
                    "countConnections": 0,
                    "countApiCalls": 102,
                    "countStorage": 1726603264
                },
                {
                    "orgKey": "ORGBUG",
                    "customerRefId": "",
                    "parentOrgKey": "DEV",
                    "countBillableThings": 0,
                    "countThings": 0,
                    "countConnections": 0,
                    "countApiCalls": 102,
                    "countStorage": 17100800
                }
            ]
        }
    }
}

Response Parameters

Name Type Description
header Object The header object.
report Array Array of report objects.
countsByThingDef Array Array of Thing definition count records.
countsByType Array Array of Type count records.

Header Object

Name Type Description
orgKey String The key associated with the organization.
orgId String The unique identifier associated with the organization.
orgName String The name associated with the organization.
customerRefId String The customer reference ID associated with the organization.
start String The timestamp representing the beginning of the billing period.
end String The timestamp representing the end of the billing period.

Report Object

Name Type Description
orgKey String The key associated with the organization.
customerRefId String The customer reference ID associated with the organization.
parentOrgKey String The key associated with the organization's parent.
countBillableThings Integer The count of billable things.
countThings Integer The count of total things, billable or not.
countConnections Integer The count of total connections.
countApiCalls Integer The count of the total API calls made in that organization.
countStorage Integer The count of total storage used in the organization, in bytes.

To convert to MB or GB to match the billing report it is necessary to use 1024 as a multiplier.

1 MB being equals to 1024 bytes; 1 GB being equals to 1024 MB and so on.
totalPrice Float The total price for that billing item for that month.
countLwm2mMessages Integer The total number of LwM2M messages.
countTriggerActions Integer The total number of trigger and campaign actions executed.
countSms Integer The total number of SMS messages sent and received.

countsByThingDef Object

Name Type Description
orgKey String The organization key.
defKey String The Thing definition key.
countBillableThings Integer The total number of billable Things of this Thing definition.
countThings Integer The total number of Things of this Thing definition.

countsByType

Name Type Description
orgKey String The organization key.
type String The type of devices counted: gateway, lwm2m, lora, or generic.
countBillableThings Integer The total number of billable Things of this type.
countThings Integer The total number of Things of this type.