homechevron_rightDocschevron_rightAPI Referencechevron_rightNotehub APIchevron_rightUsage API - Notehub API Reference

Usage API

The Notehub usage API provides RESTful methods that can be used to retrieve usage data and metrics for projects, including data consumption, event counts, route logs, and session information.

Name	HTTP Request
Get Data Usage	GET `/v1/projects/{projectOrProductUID}/usage/data`
Get Events Usage	GET `/v1/projects/{projectOrProductUID}/usage/events`
Get Sessions Usage	GET `/v1/projects/{projectOrProductUID}/usage/sessions`

Get Data Usage Notehub

Get data usage in bytes for a project with time range and period aggregation.

HTTP Method:	`GET`
URL:	`https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/data`
Path Parameters:	`projectOrProductUID` - The ProjectUID or ProductUID of a Notehub project.
Minimum Notehub project-level role:	viewer
Required HTTP Headers:	`Authorization: Bearer <token>`, where the token is a valid authentication token.

Arguments

`period`

string (required)

Period type for aggregation. Valid values include "day", "week", and "month".

`startDate`

integer (optional)

Start date for filtering results, specified as a Unix timestamp.

`endDate`

integer (optional)

End date for filtering results, specified as a Unix timestamp.

`deviceUID`

Array (optional)

An array of DeviceUIDs to filter the usage data by specific devices.

`fleetUID`

Array (optional)

An array of FleetUIDs to filter usage data by.

`aggregate`

string (optional)

Aggregation level for results. Valid values include "device", "fleet", and "project".

Basic

Bash

curl -X GET
   -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/data?period=<period>'
   -H 'Authorization: Bearer <access_token>'

import * as NotehubJs from "@blues-inc/notehub-js";
let defaultClient = NotehubJs.ApiClient.instance;
// Configure Bearer access token for authorization: personalAccessToken
let personalAccessToken = defaultClient.authentications["personalAccessToken"];
personalAccessToken.accessToken = "YOUR ACCESS TOKEN";

let apiInstance = new NotehubJs.UsageApi();
let projectOrProductUID = "app:2606f411-dea6-44a0-9743-1130f57d77d8"; // String |
let period = "day"; // String | Period type for aggregation
let opts = {
  startDate: 1628631763, // Number | Start date for filtering results, specified as a Unix timestamp
  endDate: 1657894210, // Number | End date for filtering results, specified as a Unix timestamp
  deviceUID: ["dev:000000000000000"], // [String] | A Device UID.
  fleetUID: ["fleet:000000000000000"], // [String] | A Fleet UID.
  aggregate: "device" // String | Aggregation level for results
};
apiInstance.getDataUsage(projectOrProductUID, period, opts).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  },
  (error) => {
    console.error(error);
  }
);

Python

import notehub_py
from notehub_py.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.notefile.net
configuration = notehub_py.Configuration(
    host = "https://api.notefile.net"
)

# Configure Bearer authorization: personalAccessToken
configuration = notehub_py.Configuration(
    access_token = os.environ["BEARER_TOKEN"]
)

# Enter a context with an instance of the API client
with notehub_py.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8" # str |
    period = "day" # str | Period type for aggregation
    start_date = 1628631763 # int | Start date for filtering results, specified as a Unix timestamp (optional)
    end_date = 1657894210 # int | End date for filtering results, specified as a Unix timestamp (optional)
    device_uid = ["device_uid_example"] # List[str] | A Device UID. (optional)
    fleet_uid = ["fleet_uid_example"] # List[str] | A Fleet UID. (optional)
    aggregate = "device" # str | Aggregation level for results (optional)

    try:
        api_response = api_instance.get_data_usage(project_or_product_uid, period, start_date=start_date, end_date=end_date, device_uid=device_uid, fleet_uid=fleet_uid, aggregate=aggregate)
        print("The response of UsageApi->get_data_usage:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling UsageApi->get_data_usage: %s\n" % e)

Optional Params

Bash

curl -X GET
   -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/data?period=<period>&startDate=<startDate>&endDate=<endDate>&deviceUID=<deviceUID>&fleetUID=<fleetUID>&aggregate=<aggregate>'
   -H 'Authorization: Bearer <access_token>'

Response Members

`type`

_string _

The type of connection used by the device. Valid values are "cellular" or "satellite".

`device`

string (optional)

The Device UID this usage data belongs to (only present when aggregate is "device").

`fleet`

string (optional)

The Fleet UID this usage data belongs to (only present when aggregate is "fleet").

`iccid`

string (optional)

The ICCID for the SIM card associated with this usage data. This field is only present when the type is "cellular".

`imsi`

string (optional)

The IMSI for the SIM card associated with this usage data. This field is only present when the type is "satellite".

`data`

array of objects

An array of data usage objects, each containing the following fields:

`data.period`

string (date)

The time period for this usage aggregation.

`data.total_bytes`

integer

The total number of bytes (sent and received) recorded during the specified period.

`data.bytes_received`

integer (optional)

The number of bytes received during the specified period.

`data.bytes_sent`

integer (optional)

The number of bytes sent during the specified period.

Example Response

[
  {
    "device": "dev:000000000000000",
    "type":  "cellular",
    "iccid": "xxxxxxxxxxxxxxxxxxxx",
    "data": [
      {
        "period": "2023-08-16T00:00:00Z",
        "total_bytes": 80235,
        "bytes_received": 12345,
        "bytes_sent": 67890
      }
    ]
  },
  {
    "device": "dev:111111111111111",
    "type":  "satellite",
    "imsi": "xxxxxxxxxxxxxxxx", 
    "data": [
      {
        "period": "2023-08-16T00:00:00Z",
        "total_bytes": 123456,
        "bytes_received": 23456,
        "bytes_sent": 100000
      }
    ]
  }
]

Get Events Usage Notehub

Get events usage for a project with time range and period aggregation.

HTTP Method:	`GET`
URL:	`https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/events`
Path Parameters:	`projectOrProductUID` - The ProjectUID or ProductUID of a Notehub project.
Minimum Notehub project-level role:	viewer
Required HTTP Headers:	`Authorization: Bearer <token>`, where the token is a valid authentication token.

Arguments

`period`

string (required)

Period type for aggregation. Valid values include "day", "week", and "month".

`startDate`

integer (optional)

Start date for filtering results, specified as a Unix timestamp.

`endDate`

integer (optional)

End date for filtering results, specified as a Unix timestamp. When endDate is 0 or unspecified the current time is implied.

`deviceUID`

Array (optional)

An array of DeviceUIDs to filter the usage data by specific devices.

`fleetUID`

Array (optional)

An array of FleetUIDs to filter usage data by.

`aggregate`

string (optional)

Aggregation level for results. Valid values include "device", "fleet", and "project".

Basic

Bash

curl -X GET
   -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/events?period=<period>'
   -H 'Authorization: Bearer <access_token>'

import * as NotehubJs from "@blues-inc/notehub-js";
let defaultClient = NotehubJs.ApiClient.instance;
// Configure Bearer access token for authorization: personalAccessToken
let personalAccessToken = defaultClient.authentications["personalAccessToken"];
personalAccessToken.accessToken = "YOUR ACCESS TOKEN";

let apiInstance = new NotehubJs.UsageApi();
let projectOrProductUID = "app:2606f411-dea6-44a0-9743-1130f57d77d8"; // String |
let period = "day"; // String | Period type for aggregation
let opts = {
  startDate: 1628631763, // Number | Start date for filtering results, specified as a Unix timestamp
  endDate: 1657894210, // Number | End date for filtering results, specified as a Unix timestamp
  deviceUID: ["dev:000000000000000"], // [String] | A Device UID.
  fleetUID: ["fleet:000000000000000"], // [String] | A Fleet UID.
  aggregate: "device" // String | Aggregation level for results
};
apiInstance.getProjectEventsUsage(projectOrProductUID, period, opts).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  },
  (error) => {
    console.error(error);
  }
);

Python

import notehub_py
from notehub_py.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.notefile.net
configuration = notehub_py.Configuration(
    host = "https://api.notefile.net"
)

# Configure Bearer authorization: personalAccessToken
configuration = notehub_py.Configuration(
    access_token = os.environ["BEARER_TOKEN"]
)

# Enter a context with an instance of the API client
with notehub_py.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8" # str |
    period = "day" # str | Period type for aggregation
    start_date = 1628631763 # int | Start date for filtering results, specified as a Unix timestamp (optional)
    end_date = 1657894210 # int | End date for filtering results, specified as a Unix timestamp (optional)
    device_uid = ["device_uid_example"] # List[str] | A Device UID. (optional)
    fleet_uid = ["fleet_uid_example"] # List[str] | A Fleet UID. (optional)
    aggregate = "device" # str | Aggregation level for results (optional) (default to "device")

    try:
        api_response = api_instance.get_events_usage(project_or_product_uid, period, start_date=start_date, end_date=end_date, device_uid=device_uid, fleet_uid=fleet_uid, aggregate=aggregate)
        print("The response of UsageApi->get_project_events_usage:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling UsageApi->get_project_events_usage: %s\n" % e)

Optional Params

Bash

curl -X GET
   -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/events?period=<period>&startDate=<startDate>&endDate=<endDate>&deviceUID=<deviceUID>&fleetUID=<fleetUID>&aggregate=<aggregate>'
   -H 'Authorization: Bearer <access_token>'

Response Members

`device`

string (optional)

The Device UID this usage data belongs to (only present when aggregate is "device").

`fleet`

string (optional)

The Fleet UID this usage data belongs to (only present when aggregate is "fleet").

`period`

string (date)

The time period for this usage aggregation.

`platform_events`

integer

The number of platform events recorded during the specified period.

`total_events`

integer

The total number of events recorded during the specified period.

`watchdog_events`

The total number of watchdog events recorded during the specified period.

Example Response

[
  {
    "device": "dev:000000000000000",
    "period": "2023-08-15T00:00:00Z",
    "platform_events": 12,
    "total_events": 25,
    "watchdog_events": 3
  },
  {
    "device": "dev:111111111111111",
    "period": "2023-08-16T00:00:00Z",
    "platform_events": 8,
    "total_events": 18,
    "watchdog_events": 2
  },
  {
    "device": "dev:222222222222222",
    "period": "2023-08-15T00:00:00Z",
    "platform_events": 5,
    "total_events": 10,
    "watchdog_events": 1
  }
]

Get Sessions Usage Notehub

Get sessions usage for a project with time range and period aggregation.

HTTP Method:	`GET`
URL:	`https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/sessions`
Path Parameters:	`projectOrProductUID` - The ProjectUID or ProductUID of a Notehub project.
Minimum Notehub project-level role:	viewer
Required HTTP Headers:	`Authorization: Bearer <token>`, where the token is a valid authentication token.

Arguments

`period`

string (required)

Period type for aggregation. Valid values include "day", "week", and "month".

`startDate`

integer (optional)

Start date for filtering results, specified as a Unix timestamp.

`endDate`

integer (optional)

End date for filtering results, specified as a Unix timestamp. When endDate is 0 or unspecified the current time is implied.

`deviceUID`

array (optional)

An array of DeviceUIDs to filter the usage data by specific devices.

`fleetUID`

Array (optional)

An array of FleetUIDs to filter usage data by.

`aggregate`

string (optional)

Aggregation level for results. Valid options include "device", "fleet", and "project".

Basic

Bash

curl -X GET
   -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/sessions?period=<period>'
   -H 'Authorization: Bearer <access_token>'

import * as NotehubJs from "@blues-inc/notehub-js";
let defaultClient = NotehubJs.ApiClient.instance;
// Configure Bearer access token for authorization: personalAccessToken
let personalAccessToken = defaultClient.authentications["personalAccessToken"];
personalAccessToken.accessToken = "YOUR ACCESS TOKEN";

let apiInstance = new NotehubJs.UsageApi();
let projectOrProductUID = "app:2606f411-dea6-44a0-9743-1130f57d77d8"; // String |
let period = "day"; // String | Period type for aggregation
let opts = {
  startDate: 1628631763, // Number | Start date for filtering results, specified as a Unix timestamp
  endDate: 1657894210, // Number | End date for filtering results, specified as a Unix timestamp
  deviceUID: ["dev:000000000000000"], // [String] | A Device UID.
  fleetUID: ["fleet:000000000000000"], // [String] | A Fleet UID.
  aggregate: "device" // String | Aggregation level for results
};
apiInstance.getSessionsUsage(projectOrProductUID, period, opts).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  },
  (error) => {
    console.error(error);
  }
);

Python

import notehub_py
from notehub_py.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.notefile.net
configuration = notehub_py.Configuration(
    host = "https://api.notefile.net"
)

# Configure Bearer authorization: personalAccessToken
configuration = notehub_py.Configuration(
    access_token = os.environ["BEARER_TOKEN"]
)

# Enter a context with an instance of the API client
with notehub_py.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8" # str |
    period = "day" # str | Period type for aggregation
    start_date = 1628631763 # int | Start date for filtering results, specified as a Unix timestamp (optional)
    end_date = 1657894210 # int | End date for filtering results, specified as a Unix timestamp (optional)
    fleet_uid = ["fleet_uid_example"] # List[str] | A Fleet UID. (optional)
    device_uid = ["device_uid_example"] # List[str] | A Device UID. (optional)
    aggregate = "device" # str | Aggregation level for results (optional)

    try:
        api_response = api_instance.get_sessions_usage(project_or_product_uid, period, start_date=start_date, end_date=end_date, device_uid=device_uid, fleet_uid=fleet_uid, aggregate=aggregate)
        print("The response of UsageApi->get_sessions_usage:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling UsageApi->get_sessions_usage: %s\n" % e)

Optional Params

Bash

curl -X GET
   -L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/sessions?period=<period>&startDate=<startDate>&endDate=<endDate>&deviceUID=<deviceUID>&fleetUID=<fleetUID>&aggregate=<aggregate>'
   -H 'Authorization: Bearer <access_token>'

Response Members

`device`

string (optional)

The Device UID this usage data belongs to (only present when aggregate is "device").

`fleet`

string (optional)

The Fleet UID this usage data belongs to (only present when aggregate is "fleet").

`period`

string (date)

The time period for this usage aggregation.

`sessions`

integer

The number of sessions recorded during the specified period.

`total_bytes`

integer

The total number of bytes transferred during the sessions in the specified period.

Example Response

[
  {
    "device": "dev:000000000000000",
    "period": "2023-08-15T00:00:00Z",
    "sessions": 5,
    "total_bytes": 2048
  },
  {
    "device": "dev:000000000000000", 
    "period": "2023-08-16T00:00:00Z",
    "sessions": 3,
    "total_bytes": 1536
  },
  {
    "device": "dev:111111111111111",
    "period": "2023-08-15T00:00:00Z", 
    "sessions": 2,
    "total_bytes": 1024
  }
]

Route API