usage.api.usage

The usage.api.usage command is used to get API usage statistics for a thing or a user for a specific period of time.

Usage can be requested by specifying:

  • A definite time period using a start and end date
  • A time period defined by the "last period of time" style query (last "24h", etc.)

TR50 Request

// Definite time period request for a user
{
  "get": {
    "command": "usage.api.usage",
    "params": {
      "userId": "531e10f55d80f1096f000e44",
      "start": "2019-03-27T00:00:00.000-00:00",
      "end": "2019-03-28T00:00:00.000-00:00"
    }
  }
}
// Last period of time request for a user
{
  "get": {
    "command": "usage.api.usage",
    "params": {
      "userId": "531e10f55d80f1096f000e44",
      "last": "24h"
    }
  }
}

// Definite time period request for a thing
{
  "get": {
    "command": "usage.api.usage",
    "params": {
      "thingId": "531e10f55d80f1096f000e44",
      "start": "2019-03-27T00:00:00.000-00:00",
      "end": "2019-03-28T00:00:00.000-00:00"
    }
  }
}

// Last period of time request for a thing
{
  "get": {
    "command": "usage.api.usage",
    "params": {
      "thingId": "531e10f55d80f1096f000e44",
      "last": "24h"
    }
  }
}

Request Parameters

Name Type Required Description
userId String The ID of the user to acquire usage statistics for.

Thing Identifier Parameters (see below)

String The ID of the thing to for which you need to acquire usage statistics.
last String Valid time units are seconds (s), minutes (m), hours (h), or days (d).
start String Timestamp.
end String Timestamp.

Thing Identifier Parameters

Name Type Description
thingKey String Key of the thing
thingId String Id of the thing
esn String Esn of the thing
iccid String Iccid of the thing
imei String Imei of the thing
imsi String Imsi of the thing
meid String Meid of the thing
msisdn String Msisdn of the thing

TR50 Response

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

{
  "get": {
    "success": true,
    "params": {
      "counters": {
        "usage": [0, 0, 0, 0, 1],
        ...
      },
      "total": 42,
      "ts": [
        "2019-01-20T08:00:00-05:00",
        "2019-01-20T09:00:00-05:00",
        "2019-01-20T10:00:00-05:00",
        "2019-01-20T11:00:00-05:00",
        "2019-01-20T12:00:00-05:00"
      ]
    }
  }
}

Response Parameters

Name Type Description
counters Object An object, keyed by the name of the service, that has an array expressing the number of API calls that took place during the time period in the corresponding position in the ts array below.
total Integer The total of all values in the counter object structure.
ts Array An array of the timestamps associated with the counter values.