--- title: Usage API - Notehub API Reference description: The Notehub usage API provides RESTful methods to retrieve usage data and metrics for data, events, route logs, and sessions. source_url: https://dev.blues.io/api-reference/notehub-api/usage-api/ canonical_url: https://dev.blues.io/api-reference/notehub-api/usage-api/ markdown_url: https://dev.blues.io/api-reference/notehub-api/usage-api.md --- # Usage API The Notehub usage API provides RESTful methods that can be used to retrieve usage data and metrics for [projects](https://dev.blues.io/api-reference/glossary.md#project), including data consumption, event counts, route logs, and session information. | Name | HTTP Request | | ----------------------------------------- | ------------------------------------------------------------- | | [Get Data Usage](#get-data-usage) | **GET** `/v1/projects/{projectOrProductUID}/usage/data` | | [Get Events Usage](#get-events-usage) | **GET** `/v1/projects/{projectOrProductUID}/usage/events` | | [Get Route Usage](#get-route-usage) | **GET** `/v1/projects/{projectOrProductUID}/usage/route-logs` | | [Get Sessions Usage](#get-sessions-usage) | **GET** `/v1/projects/{projectOrProductUID}/usage/sessions` | ## Get Data Usage (Notehub) Get data usage in bytes for a [project](https://dev.blues.io/api-reference/glossary.md#project), and aggregate results by device, fleet, or project. | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `GET` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/data` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | 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](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of [DeviceUIDs](https://dev.blues.io/api-reference/glossary.md#deviceuid) to filter usage data by. ### `fleetUID` *Array (optional)* An [array](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of [FleetUIDs](https://dev.blues.io/api-reference/glossary.md#fleetuid) 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. ### `limit` *integer (optional)* The maximum number of data points to return. **Basic** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//usage/data?period=' -H 'Authorization: Bearer ' ``` **JS** ```javascript 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** ```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** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//usage/data?period=&startDate=&endDate=&deviceUID=&fleetUID=&aggregate=' -H 'Authorization: Bearer ' ``` **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"`). ### `device_count` *integer* The number of devices represented in the current object. ### `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"`. ### `psid` *string (optional)* The Packet Service ID. This field is only present when the `type` is `"satellite"`. ### `truncated` *boolean* Whether the results were truncated based on the provided arguments. ### `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.downlink_bytes` *integer (optional)* The number of bytes received during the specified period. ### `data.uplink_bytes` *integer (optional)* The number of bytes sent during the specified period. ### `data.downlink_bytes_billable` *integer (optional)* The number of billable bytes received by a device. This field is only present when the `type` is `"satellite"`. ### `data.uplink_bytes_billable` *integer (optional)* The number of billable bytes sent by a device. This field is only present when the `type` is `"satellite"`. ### `data.billable_bytes_total` *integer (optional)* The total number of billable bytes sent and received by a device. This field is only present when the `type` is `"satellite"`. ### `downlink_packets` *integer (optional)* The number of packets received by a device. This field is only present when the `type` is `"satellite"`. ### `uplink_packets` *integer (optional)* The number of packets sent by a device. This field is only present when the `type` is `"satellite"`. Example Response ```json { "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", "psid": "skylo:1111111111111", "data": [ { "period": "2026-01-19T00:00:00Z", "total_bytes": 824, "downlink_bytes": 36, "uplink_bytes": 788, "downlink_bytes_billable": 50, "uplink_bytes_billable": 950, "billable_bytes_total": 1000, "downlink_packets": 1, "uplink_packets": 19 } ] } ] } ``` ## Get Events Usage (Notehub) Get event usage for a [project](https://dev.blues.io/api-reference/glossary.md#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: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | 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](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of [DeviceUID](https://dev.blues.io/api-reference/glossary.md#deviceuid) to filter usage data by. ### `fleetUID` *Array (optional)* An [array](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of [FleetUID](https://dev.blues.io/api-reference/glossary.md#fleetuid) to filter usage data by. ### `notefile` *Array (optional)* An [array](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of [Notefile](https://dev.blues.io/api-reference/glossary.md#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. ### `skipRecentData` *boolean (optional, default to `false`)* When true, skips fetching recent data from raw event tables and only returns data from summary tables. Use this for better performance on large projects. ### `includeNotefiles` *boolean (optional, default to `false`)* When true, includes per-Notefile event counts in the response. ### `limit` *integer (optional)* The maximum number of data points to return. **Basic** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//usage/events?period=' -H 'Authorization: Bearer ' ``` **JS** ```javascript 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 notefile: ["notefile_example"], // [String] | Filter to specific notefiles skipRecentData: false, // Boolean | When true, skips fetching recent data from raw event tables and only returns data from summary tables. Use this for better performance on large projects. includeNotefiles: false // Boolean | When true, includes per-Notefile event counts in the response. }; apiInstance.getProjectEventsUsage(projectOrProductUID, period, opts).then( (data) => { console.log( "API called successfully. Returned data: " + JSON.stringify(data) ); }, (error) => { console.error(error); } ); ``` **Python** ```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") notefile = ["notefile_example"] # List[str] | Filter to specific notefiles (optional) skip_recent_data = False # bool | When true, skips fetching recent data from raw event tables and only returns data from summary tables. Use this for better performance on large projects. (optional) (default to False) include_notefiles = False # bool | Include per-notefile event counts in the response (optional) (default to False) 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, notefile=notefile, skip_recent_data=skip_recent_data, include_notefiles=include_notefiles) 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** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//usage/events?period=&startDate=&endDate=&deviceUID=&fleetUID=&aggregate=¬efile=&skipRecentData=&includeNotefiles=' -H 'Authorization: Bearer ' ``` **Response Members** ### `truncated` *boolean* Whether the results were truncated based on the provided arguments. ### `data` *array of objects* An array of objects with event-usage data. Each object may contain the following fields: ### `data.device` *string (optional)* The DeviceUID this usage data belongs to (only present when `aggregate` is `"device"`). ### `data.fleet` *string (optional)* The FleetUID this usage data belongs to (only present when `aggregate` is `"fleet"`). ### `data.notefiles` *object (optional)* An object containing Notefile-specific usage data (only present when `includeNotefiles=true` is specified). ### `data.period` *string (date)* The time period for this usage aggregation. ### `data.platform_events` *integer* The number of [platform events](https://dev.blues.io/api-reference/glossary.md#platform-event) recorded during the specified period. ### `data.total_events` *integer* The total number of events recorded during the specified period. ### `data.billable_events` *integer* The total number of billable events. ### `data.watchdog_events` *integer* The total number of [watchdog events](https://dev.blues.io/notehub/notehub-walkthrough.md#using-watchdog-events) recorded during the specified period. ### `data.total_devices` *integer* The total number of devices in the specified period and aggregation. ### `data.total_days_in_period` *integer* The total number of days in the returned period, which can be useful for calculating daily averages. Note that the current period can include days in the future. ### `data.total_fw_updates` *integer* The number of firmware updates in the specified period. ### `data.total_reboots` *integer* The number of device reboots in the specified period. Example Response ```json { "data": [ { "device": "dev:000000000000000", "period": "2023-08-15T00:00:00Z", "platform_events": 12, "total_events": 25, "watchdog_events": 3, "total_devices": 1 }, { "device": "dev:111111111111111", "period": "2023-08-16T00:00:00Z", "platform_events": 8, "total_events": 18, "watchdog_events": 2, "total_devices": 1 }, { "device": "dev:222222222222222", "period": "2023-08-15T00:00:00Z", "platform_events": 5, "total_events": 10, "watchdog_events": 1, "total_devices": 1 } ] } ``` ## Get Route Usage (Notehub) Get route usage data for a [project](https://dev.blues.io/api-reference/glossary.md#project), and aggregate results by route or project. | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `GET` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/route-logs` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | 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. ### `routeUID` *Array (optional)* An [array](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) 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}`. ### `skipRecentData` *boolean (optional, defaults to `false`)* When `true`, skips fetching recent data from raw event tables and only returns data from summary tables. Use this for better performance on large projects. ### `limit` *integer (optional)* The maximum number of data points to return. **Basic** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//usage/route-logs?period=' -H 'Authorization: Bearer ' ``` **JS** ```js 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 = "period_example"; // 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 "routeUID": ["null"], // [String] | A Route UID. "aggregate": "route", // String | Aggregation level for results "skipRecentData": false // Boolean (optional) }; apiInstance.getRouteLogsUsage(projectOrProductUID, period, opts).then((data) => { console.log("API called successfully. Returned data: " + JSON.stringify(data)); }, (error) => { console.error(error); }); ``` **Python** ```python import notehub_py from notehub_py.models.get_route_logs_usage200_response import GetRouteLogsUsage200Response from notehub_py.rest import ApiException from pprint import pprint # Defining the host is optional and defaults to https://api.notefile.net # See configuration.py for a list of all supported configuration parameters. configuration = notehub_py.Configuration( host = "https://api.notefile.net" ) # The client must configure the authentication and authorization parameters # in accordance with the API server security policy. # Examples for each auth method are provided below, use the example that # satisfies your auth use case. # 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 = "period_example" # 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) route_uid = ["route_uid_example"] # List[str] | A Route UID. (optional) aggregate = "route" # str | Aggregation level for results (optional) (default to 'route') skip_recent_data = False # bool (optional) try: api_response = api_instance.get_route_logs_usage(project_or_product_uid, period, start_date=start_date, end_date=end_date, route_uid=route_uid, aggregate=aggregate) print("The response of UsageApi->get_route_logs_usage:\n") pprint(api_response) except Exception as e: print("Exception when calling UsageApi->get_route_logs_usage: %s\n" % e) ``` **Response Members** ### `truncated` *boolean* Whether the results were truncated based on the provided arguments. ### `route_logs` *array of objects* An array of objects with route-usage data. Each object may contain the following fields: ### `route_logs.route` *string* The RouteUID of the current usage aggregation. (Only in response when `"aggregate"` is set to `"route"`.) ### `route_logs.period` *string (date)* The time period for this usage aggregation. ### `route_logs.failed_routes` *integer* The number of failed route executions during the specified period. ### `route_logs.successful_routes` *integer* The number of successful route executions during the specified period. ### `route_logs.total_routes` *integer* The total number of route executions (successful + failed) during the specified period. Example Response ```json { "truncated": false, "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](https://dev.blues.io/api-reference/glossary.md#project), and aggregate results by device, fleet, or project. | | | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP Method: | `GET` | | URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/sessions` | | Path Parameters: | - `projectOrProductUID` - The [ProjectUID](https://dev.blues.io/api-reference/glossary.md#projectuid) or [ProductUID](https://dev.blues.io/api-reference/glossary.md#productuid) of a Notehub project. | | Minimum Notehub [project-level role:](https://dev.blues.io/notehub/notehub-walkthrough.md#collaborator-roles) | viewer | | Required HTTP Headers: | `Authorization: Bearer `, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). | 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](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of [DeviceUIDs](https://dev.blues.io/api-reference/glossary.md#deviceuid) to filter session data by. ### `fleetUID` *Array (optional)* An [array](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of [FleetUIDs](https://dev.blues.io/api-reference/glossary.md#fleetuid) 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. ### `skipRecentData` *boolean (optional, default to `false`)* When true, skips fetching recent data from raw event tables and only returns data from summary tables. Use this for better performance on large projects. ### `limit` *integer (optional)* The maximum number of data points to return. **Basic** **Bash** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//usage/sessions?period=' -H 'Authorization: Bearer ' ``` **JS** ```javascript 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 skipRecentData: false // Boolean | When true, skips fetching recent data from raw event tables and only returns data from summary tables. Use this for better performance on large projects. }; apiInstance.getSessionsUsage(projectOrProductUID, period, opts).then( (data) => { console.log( "API called successfully. Returned data: " + JSON.stringify(data) ); }, (error) => { console.error(error); } ); ``` **Python** ```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) skip_recent_data = False # bool | When true, skips fetching recent data from raw event tables and only returns data from summary tables. Use this for better performance on large projects. (optional) (default to False) 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, skip_recent_data=skip_recent_data) 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** ```bash curl -X GET -L 'https://api.notefile.net/v1/projects//usage/sessions?period=&startDate=&endDate=&deviceUID=&fleetUID=&aggregate=&skipRecentData=' -H 'Authorization: Bearer ' ``` **Response Members** ### `truncated` *boolean* Whether the results were truncated based on the provided arguments. ### `sessions` *array of objects* An array of objects with session-usage data. Each object may contain the following fields: ### `sessions.device` *string (optional)* The DeviceUID this usage data belongs to (only present when `aggregate` is `"device"`). ### `sessions.fleet` *string (optional)* The FleetUID this usage data belongs to (only present when `aggregate` is `"fleet"`). ### `sessions.period` *string (date)* The time period for this usage aggregation. ### `sessions.sessions` *integer* The number of sessions recorded during the specified period. ### `sessions.total_bytes` *integer* The total number of bytes transferred during the sessions in the specified period. ### `sessions.total_devices` *integer* The total number of devices in the specified period and aggregation. ### `sessions.first_sync_sessions` *integer* The number of “first sync” sessions in the specified period, where “first sync” sessions are sessions that begin when a device syncs with Notehub for the first time after being provisioned or factory-reset. ### `sessions.sessions_by_transport` `integer` Count of sessions grouped by transport type (e.g. cell, wifi, ntn, lorawan). Example Response ```json { "truncate": false, "sessions": [ { "device": "dev:000000000000000", "period": "2026-01-01T00:00:00Z", "sessions": 10, "total_bytes": 2048, "total_devices": 1, "first_sync_sessions": 0, "sessions_by_transport": { "cell": 5 } } ] } ``` [Route API](https://dev.blues.io/api-reference/notehub-api/route-api.md "Route API")