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 Route Usage | GET /v1/projects/{projectOrProductUID}/usage/route-logs |
| Get Sessions Usage | GET /v1/projects/{projectOrProductUID}/usage/sessions |
Get Data Usage Notehub
Get data usage in bytes for a project, and aggregate results by device, fleet, or project.
| HTTP Method: | GET |
| URL: | https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/data |
| Path Parameters: |
|
| Minimum Notehub project-level role: | viewer |
| Required HTTP Headers: | Authorization: Bearer <token>, where the token is a valid authentication token. |
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 usage data by.
fleetUID
Array (optional)
An array of FleetUIDs to filter usage data by.
aggregate
string (optional)
The type of aggregation to use in the response data.
"device" (default) - Group response data by device.
"fleet" - Group response data by fleet.
"project" - Group response data by project.
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);
}
);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)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 DeviceUID this usage data belongs to (only present when aggregate is "device").
fleet
string (optional)
The FleetUID 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.
{
"data": [
{
"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 event usage for a project, and aggregate results by device, fleet, project, or Notefile.
| HTTP Method: | GET |
| URL: | https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/events |
| Path Parameters: |
|
| Minimum Notehub project-level role: | viewer |
| Required HTTP Headers: | Authorization: Bearer <token>, where the token is a valid authentication token. |
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 DeviceUID to filter usage data by.
fleetUID
Array (optional)
An array of FleetUID to filter usage data by.
notefile
Array (optional)
An array of Notefile names to filter usage data by.
aggregate
string (optional)
The type of aggregation to use in the response data. There are three primary aggregate types and you may specify one:
"device" (default) - Group response data by device.
"fleet" - Group response data by fleet.
"project" - Group response data by project.
A fourth aggregation type, "notefile" may optionally be added to include
Notefile-specific usage data in the response. The following are valid ways
to use the "notefile" aggregation type:
aggregate=notefile - Device-level aggregation with Notefile usage included.
aggregate=fleet&aggregate=notefile - Fleet-level aggregation with Notefile usage
included.
aggregate=project&aggregate=notefile - Project-level aggregation with Notefile
usage included.
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);
}
);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)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 DeviceUID this usage data belongs to (only present when aggregate is "device").
fleet
string (optional)
The FleetUID this usage data belongs to (only present when aggregate is "fleet").
notefiles
object (optional)
An object containing Notefile-specific usage data (only present when aggregate is
"notefile").
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.
{
"data": [
{
"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 Route Usage Notehub
Get route usage data for a project, and aggregate results by route or project.
| HTTP Method: | GET |
| URL: | https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/route-logs |
| Path Parameters: |
|
| Minimum Notehub project-level role: | viewer |
| Required HTTP Headers: | Authorization: Bearer <token>, where the token is a valid authentication token. |
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.
routeUID
Array (optional)
An array of RouteUID to filter by.
aggregate
string (optional)
The type of aggregation to use in the response data.
"route" (default) - Group the response data by route, e.g.
[{"route":"route1","total_routes":1},{"route":"route2","total_routes":1}].
"project" - Group the response data by project, e.g. {"total_routes": 2}.
curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/route-logs?period=<period>'
-H 'Authorization: Bearer <access_token>'curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectOrProductUID>/usage/route-logs?period=<period>&startDate=<startDate>&endDate=<endDate>&aggregate=<aggregate>'
-H 'Authorization: Bearer <access_token>'Response Members
route
string
The RouteUID of the current usage aggregation. (Only in response when
"aggregate" is set to "route".)
period
string (date)
The time period for this usage aggregation.
failed_routes
integer
The number of failed route executions during the specified period.
successful_routes
integer
The number of successful route executions during the specified period.
total_routes
integer
The total number of route executions (successful + failed) during the specified period.
{
"route_logs": [
{
"route": "route:27b6ab54d9562ed03c0c9e98627e8950",
"period": "2025-11-06T00:00:00Z",
"successful_routes": 21631,
"failed_routes": 0,
"total_routes": 21631
},
{
"route": "route:c28a25e26f90fb6fb64bb51a8a65e877",
"period": "2025-11-06T00:00:00Z",
"successful_routes": 21630,
"failed_routes": 1,
"total_routes": 21631
}
]
}Get Sessions Usage Notehub
Get session usage for a project, and aggregate results by device, fleet, or project.
| HTTP Method: | GET |
| URL: | https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/sessions |
| Path Parameters: |
|
| Minimum Notehub project-level role: | viewer |
| Required HTTP Headers: | Authorization: Bearer <token>, where the token is a valid authentication token. |
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 session data by.
fleetUID
Array (optional)
An array of FleetUIDs to filter session data by.
aggregate
string (optional)
The type of aggregation to use in the response data.
"device" (default) - Group response data by device.
"fleet" - Group response data by fleet.
"project" - Group response data by project.
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);
}
);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)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 DeviceUID this usage data belongs to (only present when aggregate is "device").
fleet
string (optional)
The FleetUID 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.
{
"sessions": [
{
"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
}
]
}