usage.sharing.list

The usage.sharing.list command lists object sharing activity.

Usage sharing history is requested by specifying:

A definite time period using a start and end date
To query on last few days or few hours or few minutes (For example, 24h, 180m, 113000s, 120d)
To query on last few days or few hours or few minutes for a specific Thing or a Connection

TR50 Request

// Definite time period request
{
  "get": {
    "command": "usage.sharing.list",
    "params": {
        "offset": 0,
        "limit": 10,
        "start": "2017-02-03T04:13:22Z",
        "end": "2017-06-08T12:00:00Z"
    }
  }
}

// Last period of time request
{
  "get": {
    "command": "usage.sharing.list",
    "params": {
        "offset": 0,
        "limit": 10,
        "last":"24h"
    }
  }
}

// Definite time period request for a specific thing
{
  "get": {
    "command": "usage.sharing.list",
    "params": {
        "start": "2017-02-03T04:13:22Z",
        "end": "2017-06-08T12:00:00Z",
        "key": "some_thing_key"
    }
  }
}

// Last period of time request for a specific connection
{
  "get": {
    "command": "usage.sharing.list",
    "params": {
        "last":"420m",
        "iccid": "76483827273872729993726"
    }
  }
}

Request Parameters

Name	Type	Description
offset	Integer	The starting list offset, used for pagination, defaults to 0 if not specified.
limit	Integer	The list limit, used for pagination, defaults to the maximum configured size.
last	String	Return last X records in one of the valid time units: "ns", "us", "ms", "s", "m", "h".
showAll	Boolean	If all organizations should be included in this view. Requires Super ops or higher access.
start	String	Provide the start Timestamp. You need to provide an end timestamp.
end	String	Provide the end Timestamp. You need to provide an start timestamp.
key	String	Limit result to a Thing key.
iccid	String	Limit result to an ICCID.
esn	String	Limit result to an ESN.
imei	String	Limit result to an IMEI.
meid	String	Limit result to a MEID.
imsi	String	Limit result to an IMSI.

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.

{
  "cmd": {
    "success": true,
    "params": {
      "count": 2,
      "result": [
        {
          "id": "s0m30bj3ct1d",
          "type": "share",
          "ts": "2017-10-24T15:46:23Z",
          "whoami": "user@example.com",
          "orgId": "s0m30rg1d",
          "thingId": "s0m3th1ng1d",
          "thingKey": "mah_thing_key",
          "targetOrgId": "s0m30rg1d",
          "targetOrgKey": "SOME_ORG_KEY",
          "permission": "rw"
        },
        {
          "id": "s0m30bj3ct1d",
          "type": "unshare",
          "ts": "2017-10-24T15:48:09Z",
          "whoami": "user@example.com",
          "orgId": "s0m30rg1d",
          "thingId": "s0m3th1ng1d",
          "thingKey": "mah_thing_key",
          "targetOrgId": "s0m30rg1d",
          "targetOrgKey": "SOME_ORG_KEY",
        }
      ]
    }
  }
}

Response Parameters

Name	Type	Description
id	String	The id assigned to the log.
type	String	Either it is a Share or UnShare type.
ts	Array	An array of the timestamps associated with the connected and total values.
whoami	String	The email address of the user that made the request.
orgId	String	The organization id to which a thing or connection belongs to.
thingId	String	The unique identifier of the Thing associated with the event.
thingkey	String	The key of the thing.
identifiers	Array	An array of connection identifiers.
targetOrgId	String	The target Org id to which it the thing or connection is shared to.
targetOrgKey	String	The target Org key to which it the thing or connection is shared to.
permission	String	The permission granted to the org for the thing being shared. Valid values are "r" for read-only, and "rw" for reading & writing. Resharing is only allowed when the org is granted "rw" permission.