usage.api.list

The usage.api.list command lists the API usage logs.

API usage logs is 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.)
  • A filter parameter for improved searching performance for recent API log records.

TR50 Request

// Definite time period request
{
  "list": {
    "command": "usage.api.list",
    "params": {
      "offset": 0,
      "limit": 10,
      "showAll": false,
      "start": "2019-01-01T00:00:00Z",
      "end": "2019-01-31T23:59:59Z",
      "hasFailure": false
    }
  }
}
// list of failed thing service requests by "user@example.com" in the last 3 days 
{ 
  "1": { 
    "command": "usage.api.list", 
    "params": { 
      "offset": 0, 
      "limit": 10, 
      "filter": ["failure", "thing", "user@example.com"], 
      "last": "3d" 
    } 
  } 
}
// list of "mailbox.check" commands issued by a thing identified by the key "mythingkey" 
{ 
  "1": { 
    "command": "usage.api.list", 
    "params": { 
      "offset": 0, 
      "limit": 10, 
      "filter": ["mailbox.check", "mythingkey"] 
    } 
  } 
}

Request Parameters

Name Type Required Description
who String   The Thing key or user email that executed the commands.
service String   The service name of the commands (e.g. location).
command String   The command name (e.g. publish). Requires the service parameter to be specified.
offset Integer   The starting list offset, used for pagination, defaults to 0 if not specified.
limit Integer   The starting list offset, used for pagination. The maximum limit you can set is 2000. Defaults to 2000.
showAll Boolean   If all organizations should be included in this view. Requires Super-Ops.
last String   Valid time units are "ns", "us", "ms", "s", "m", "h".
start String   Timestamp.
end String   Timestamp.
filter Array   The filter parameter is an array of strings. Following are the possible filter values:
  • email address of the user (that made the request),
  • key of the Thing
  • name of the service in the request,
  • command
  • use keyword failureto return the failed requests
hasFailure Boolean   Set it to true will show all the failed requests otherwise set it to false.

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.

{
  "list": {
    "success": true,
    "params": {
      "count": 42,
      "result": [
        {
          "ts": "2019-02-11T14:15:34.882-05:00",
          "processedBy": "ip-10-200-40-161",
          "whoami": "admin@devicewise.com",
          "request": "{\"1\":{\"Command\":\"usage.api.list\",\"SessionId\":\"\",\"Params\":{\"last\":\"24h\"}}}",
          "response": "{\"1\":{\"success\":true,\"params\":{\"count\":0,\"result\":null}}}"
        },
        ...
      ]
    }
  }
}

Response Parameters

Name Type Description
count Integer The total number of records.
result Array The array of result objects.

Result Array Object

Name Type Description
ts String Timestamp of API call.
execTime Integer Nanoseconds used to execute the API call.
processedBy String The host that processed the request.
orgId String The organization object id.
orgKey String The organization key.
whoami String The email address of the user that made the request.
request String The request string.
response String The response string.