Documentation

Mistake on this page? Email us

Connect Statistics API

Connect Statistics API provides statistics about other cloud services through defined counters.
Version: 3
Host: http://api.us-east-1.mbedcloud.com

Endpoints

Statistics

get /v3/metrics
Provides account-specific statistics for other cloud services. Show more Show less
This REST API is used to get account-specific statistics.
Query parameters
include (required)
Query Parameter

A comma-separated list of requested metrics and total_count (if included, the response will contain total_count to specify the total number of records available). Supported values are:

  • transactions
  • full_registrations
  • registration_updates
  • deleted_registrations
  • expired_registrations
  • bootstraps_successful
  • bootstraps_failed
  • bootstraps_pending
  • handshakes_successful
  • connect_rest_api_success
  • connect_rest_api_error
  • device_proxy_request_success
  • device_proxy_request_error
  • device_subscription_request_success
  • device_subscription_request_error
  • device_observations
  • total_count

Note:

The metrics device_proxy_request_success, device_proxy_request_error, device_subscription_request_success, device_subscription_request_error and device_observations monitor only the response from the device to Device Management Connect and they do not confirm that the response is delivered to client callback URLs used when you try to access device resources using Connect API endpoints. New metrics will be added to monitor the response delivery to client callback URLs later.

Example usage:

curl  -X GET \
      -H "Authorization : Bearer <valid access Token>"
       'https://api.us-east-1.mbedcloud.com/v3/metrics?include=transactions,total_count&start=20170207&end=20170407&interval=1d'

{
    "object": "list",
    "limit": 20,
    "total_count": 54,
    "after": "2017-07-26T00:00:00Z",
    "has_more": true,
    "data": [
        {
            "id": "015d8157c800015e306fffff005374617473000",
            "timestamp": "2017-07-27T00:00:00Z",
            "transactions": 27366
        },
        {
            "id": "015d867e2400015e306fffff005374617473000",
            "timestamp": "2017-07-28T00:00:00Z",
            "transactions": 27480
        }
    ]
}
start (optional)
Query Parameter — UTC time/year/date in RFC3339 format. Fetch the data with timestamp greater than or equal to this value. Sample values: 20170207T092056990Z/2017-02-07T09:20:56.990Z / 2017 / 20170207. The maximum time between start and end parameters cannot exceed more than one year (365 days). The parameter is not mandatory, if the period is specified. format: date
end (optional)
Query Parameter — UTC time/year/date in RFC3339 format. Fetch the data with timestamp less than this value. Sample values: 20170207T092056990Z/2017-02-07T09:20:56.990Z / 2017 / 20170207. The maximum time between start and end parameters cannot exceed more than one year (365 days). The parameter is not mandatory, if the period is specified. format: date
period (optional)
Query Parameter — Period. Fetch the data for the period in minutes, hours, days or weeks. Sample values: 5m, 2h, 3d, 4w. The parameter is not mandatory, if the start and end time are specified. The maximum period cannot exceed one year (365 days). The allowed ranges are 5m-525600m/1h-8760h/1d-365d/1w-53w.
interval (required)
Query Parameter — Group the data by this interval in minutes, hours, days or weeks. Sample values: 5m, 2h, 3d, 4w. The maximum interval cannot exceed one year (365 days). The allowed ranges are 5m-525600m/1h-8760h/1d-365d/1w-53w.
limit (optional)
Query Parameter — The number of results to return. The default value is 50, minimum 2 and maximum 1000.
after (optional)
Query Parameter

The metric ID after which to start fetching. This also can be used for pagination as follows:

Example usage:

curl  -X GET \
      -H "Authorization : Bearer <valid access Token>"
       'https://api.us-east-1.mbedcloud.com/v3/metrics?include=transactions,total_count&start=20170707&end=20170829&interval=1d&limit=20'
{
   "object": "list",
   "limit": 20,
   "total_count": 54,
   "has_more": true,
   "data": [
       {
           "id": "015d1a589800015e306fffff005374617473000",
           "timestamp": "2017-07-07T00:00:00Z",
           "transactions": 26381
       },
       .
       .
       .
       {
           "id": "015d7c316c00015e306fffff005374617473000",
           "timestamp": "2017-07-26T00:00:00Z",
           "transactions": 25569
       }
   ]
}

If the parameter has more is true, it indicates that the list is not complete and more values are available. You can give the last ID of the list as the value of the after query parameter, and you get the next page of values. You can keep doing this until has more is false.

curl -X GET \
     -H "Authorization : Bearer <valid access Token>"
     'https://api.us-east-1.mbedcloud.com/v3/metrics?include=transactions,total_count&start=20170707&end=20170829&interval=1d&limit=20&after=015d7c316c00015e306fffff005374617473000'

{
   "object": "list",
   "limit": 20,
   "total_count": 54,
   "after": "2017-07-26T00:00:00Z",
   "has_more": true,
   "data": [
       {
           "id": "015d8157c800015e306fffff005374617473000",
           "timestamp": "2017-07-27T00:00:00Z",
           "transactions": 27366
       },
     .
     .
     .
       {
           "id": "015de3309c00015e306fffff005374617473000",
           "timestamp": "2017-08-15T00:00:00Z",
           "transactions": 24707
       }
   ]
}
order (optional)
Query Parameter — The order of the records to return. Available values are ASC and DESC. The default value is ASC.
Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "registration_updates" : 5,
    "device_subscription_request_success" : 6,
    "device_subscription_request_error" : 7,
    "expired_registrations" : 7,
    "device_proxy_request_error" : 1,
    "full_registrations" : 5,
    "device_proxy_request_success" : 1,
    "bootstraps_successful" : 9,
    "transactions" : 1,
    "handshakes_successful" : 4,
    "bootstraps_pending" : 2,
    "connect_rest_api_success" : 7,
    "device_observations" : 1,
    "bootstraps_failed" : 3,
    "id" : "aeiou",
    "deleted_registrations" : 2,
    "connect_rest_api_error" : 1,
    "timestamp" : "2000-01-23T04:56:07.000+00:00"
  } ],
  "total_count" : 0,
  "limit" : 6,
  "after" : "aeiou",
  "has_more" : true,
  "object" : "aeiou"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Successful response. successful-response
400 Bad request. error-response
401 Authentication failure. error-response
403 Access denied. error-response

Models

error-response

object (optional)
String Response type, always "error".
code (optional)
Integer HTTP response code. format: int32
type (optional)
String Type of error.
message (optional)
String Description of the error.
fields (optional)
array[fields] Details of the error fields.
request_id (optional)
String Request ID.

fields

name (optional)
String The field name in the request for which the validation has failed.
message (optional)
String Error description.

metric

id (optional)
String A unique metric ID.
timestamp (optional)
Date UTC time in RFC3339 format. The timestamp is the starting point of the interval for which the data is aggregated. Each interval includes data for the time greater than or equal to the timestamp and less than the next interval's starting point. format: date-time
transactions (optional)
Long The number of transaction events from or to devices linked to the account. A transaction is a 512-byte block of data processed by Device Management. It can be either sent by the device (device --> Device Management) or received by the device (Device Management --> device). A transaction does not include IP, TCP or UDP, TLS or DTLS packet overhead. It only contains the packet payload (full CoAP packet including CoAP headers). format: int64
full_registrations (optional)
Long The number of full registrations linked to the account. Full registration is the process of registering a device with Device Management Connect by providing its lifetime and capabilities such as the resource structure.The registered status of the device does not guarantee that the device is active and accessible from Device Management Connect at any point of time. format: int64
registration_updates (optional)
Long The number of registration updates linked to the account. Registration update is the process of updating the registration status with Device Management Connect to update or extend the lifetime of the device. format: int64
deleted_registrations (optional)
Long The number of deleted registrations (deregistrations) linked to the account. Deregistration is the process of removing the device registration from the Device Management Connect registry. The deregistration is usually initiated by the device. Device Management Connect no longer handles requests for a deregistered device. format: int64
expired_registrations (optional)
Long The number of expired registrations linked to the account. Device Management Connect removes the device registrations when the devices cannot update their registration before the expiry of the lifetime. Device Management Connect no longer handles requests for a device whose registration has expired already. format: int64
bootstraps_successful (optional)
Long The number of successful bootstraps the account has performed. Bootstrap is the process of provisioning a Lightweight Machine to Machine Client to a state where it can initiate a management session to a new Lightweight Machine to Machine Server. format: int64
bootstraps_failed (optional)
Long The number of failed bootstraps the account has performed. Bootstrap is the process of provisioning a Lightweight Machine to Machine Client to a state where it can initiate a management session to a new Lightweight Machine to Machine Server. format: int64
bootstraps_pending (optional)
Long The number of pending bootstraps the account has performed. Bootstrap is the process of provisioning a Lightweight Machine to Machine Client to a state where it can initiate a management session to a new Lightweight Machine to Machine Server. format: int64
handshakes_successful (optional)
Long The number of successful TLS handshakes the account has performed. The SSL or TLS handshake enables the SSL or TLS client and server to establish the secret keys with which they communicate. A successful TLS handshake is required for establishing a connection with Device Management Connect for any operaton such as registration, registration update and deregistration. format: int64
connect_rest_api_success (optional)
Long The number of successful Connect API requests that have been performed using the account. This metric does not consider the response from the device, it includes only the responses to the HTTP requests used to manage the device. format: int64
connect_rest_api_error (optional)
Long The number of failed Connect API requests that have been performed using the account. This metric does not consider the response from the device, it includes only the responses to the HTTP requests used to manage the device. This metric includes only messages handled by the Connect service, it does not include any HTTP errors returned by firewall as result of malformed messages. format: int64
device_proxy_request_success (optional)
Long (Beta) The number of successful proxy requests from the Device Management Connect service to devices linked to the account. Device Management Connect makes proxy requests to devices when you try to read or write values to device resources using Connect API endpoints. format: int64
device_proxy_request_error (optional)
Long (Beta) The number of failed proxy requests from the Device Management Connect service to devices linked to the account. Device Management Connect makes proxy requests to devices when you try to read or write values to device resources using Connect API endpoints. format: int64
device_subscription_request_success (optional)
Long (Beta) The number of successful subscription requests from the Device Management Connect service to devices linked to the account. Device Management Connect makes subscription requests to devices when you try to subscribe to a resource path using Connect API endpoints. format: int64
device_subscription_request_error (optional)
Long (Beta) The number of failed subscription requests from the Device Management Connect service to devices linked to the account. Device Management Connect makes subscription requests to devices when you try to subscribe to a resource path using Connect API endpoints. format: int64
device_observations (optional)
Long (Beta) The number of notifications received by the Device Management Connect service from the devices linked to the account. The device pushes notifications to Device Management Connect when you have successfully subscribed to the device resources using Connect API endpoints. format: int64

successful-response

object (optional)
String API resource name.
after (optional)
String The metric ID included in the request or null.
total_count (optional)
Integer The total number of records available.
has_more (optional)
Boolean Indicates whether there are more results for you to fetch in the next page.
limit (optional)
Integer The limit used in the request to retrieve the results.
data (optional)