---
title: Usage API - Notehub API Reference
description: The Notehub usage API provides RESTful methods to retrieve usage data and metrics for API requests, 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 API requests, data consumption, event counts, route logs, and session information.

| Name | HTTP Request |
| - | - |
| [Get API Usage](#get-api-usage) | **GET** `/v1/projects/{projectOrProductUID}/usage/api` |
| [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 API Usage (Notehub) {#get-api-usage}

Get billable Notehub API request usage for a [project](https://dev.blues.io/api-reference/glossary.md#project), broken down by endpoint and time period. Only requests that are billed against the project's plan are counted.

| | |
| - | - |
| HTTP Method: | `GET` |
| URL: | `https://api.notefile.net/v1/projects/{projectOrProductUID}/usage/api` |
| 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 <token>`, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). |

Arguments

### `period` {#get-api-usage--period}

*string (required)*

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

### `startDate` {#get-api-usage--startdate}

*integer (optional)*

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

### `endDate` {#get-api-usage--enddate}

*integer (optional)*

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

### `limit` {#get-api-usage--limit}

*integer (optional)*

The maximum number of data points to return.

**Basic**

**Bash**

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

**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";
let period = "day";

apiInstance.getApiUsage(projectOrProductUID, period).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data),
    );
  },
  (error) => {
    console.error(error);
  },
);
```

**Python**

```python
import os
from pprint import pprint

import notehub_py

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:
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8"
    period = "day"

    try:
        api_response = api_instance.get_api_usage(
            project_or_product_uid, period
        )
        print("The response of UsageApi->get_api_usage:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling UsageApi->get_api_usage: %s\n" % e)
```

**Optional Params**

**Bash**

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

**Response Members**

### `truncated` {#get-api-usage--truncated}

*boolean (optional)*

Whether the results were truncated based on the provided arguments.

### `data` {#get-api-usage--data}

*array of objects*

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

### `data.period` {#get-api-usage--data-period}

*string (date)*

The time period for this usage aggregation.

### `data.requests` {#get-api-usage--data-requests}

*integer*

The number of billable API requests in this period.

### `data.endpoint` {#get-api-usage--data-endpoint}

*string (optional)*

The templated path of the endpoint the requests were made against, with path parameters left unsubstituted (for example, `/v1/projects/{projectOrProductUID}/devices`). Empty if the endpoint could not be resolved for these requests.

### `data.method` {#get-api-usage--data-method}

*string (optional)*

The HTTP method of the requests counted in this data point. Empty if the endpoint could not be resolved for these requests.

Example Response

```json
{
  "data": [
    {
      "period": "2025-07-23T00:00:00Z",
      "endpoint": "/v1/projects/{projectOrProductUID}/devices",
      "method": "GET",
      "requests": 1284
    },
    {
      "period": "2025-07-23T00:00:00Z",
      "endpoint": "/v1/projects/{projectOrProductUID}/events",
      "method": "GET",
      "requests": 312
    },
    {
      "period": "2025-07-24T00:00:00Z",
      "endpoint": "/v1/projects/{projectOrProductUID}/devices",
      "method": "GET",
      "requests": 976
    }
  ],
  "truncated": false
}
```

## Get Data Usage (Notehub) {#get-data-usage}

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 <token>`, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). |

Arguments

### `period` {#get-data-usage--period}

*string (required)*

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

### `startDate` {#get-data-usage--startdate}

*integer (optional)*

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

### `endDate` {#get-data-usage--enddate}

*integer (optional)*

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

### `deviceUID` {#get-data-usage--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` {#get-data-usage--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` {#get-data-usage--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` {#get-data-usage--limit}

*integer (optional)*

The maximum number of data points to return.

**Basic**

**Bash**

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

**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";
let period = "day";

apiInstance.getDataUsage(projectOrProductUID, period).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data),
    );
  },
  (error) => {
    console.error(error);
  },
);
```

**Python**

```python
import os
from pprint import pprint

import notehub_py

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:
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8"
    period = "day"

    try:
        api_response = api_instance.get_data_usage(
            project_or_product_uid, period
        )
        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/<projectOrProductUID>/usage/data?period=<period>&startDate=<startDate>&endDate=<endDate>&deviceUID=<deviceUID>&fleetUID=<fleetUID>&aggregate=<aggregate>'
   -H 'Authorization: Bearer <access_token>'
```

**Response Members**

### `type` {#get-data-usage--type}

\_string \_

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

### `device` {#get-data-usage--device}

*string (optional)*

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

### `device_count` {#get-data-usage--devicecount}

*integer*

The number of devices represented in the current object.

### `fleet` {#get-data-usage--fleet}

*string (optional)*

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

### `iccid` {#get-data-usage--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` {#get-data-usage--psid}

*string (optional)*

The Packet Service ID. This field is only present when the `type` is `"satellite"`.

### `truncated` {#get-data-usage--truncated}

*boolean*

Whether the results were truncated based on the provided arguments.

### `data` {#get-data-usage--data}

*array of objects*

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

### `data.period` {#get-data-usage--data-period}

*string (date)*

The time period for this usage aggregation.

### `data.total_bytes` {#get-data-usage--data-totalbytes}

*integer*

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

### `data.downlink_bytes` {#get-data-usage--data-downlinkbytes}

*integer (optional)*

The number of bytes received during the specified period.

### `data.uplink_bytes` {#get-data-usage--data-uplinkbytes}

*integer (optional)*

The number of bytes sent during the specified period.

### `data.downlink_bytes_billable` {#get-data-usage--data-downlinkbytesbillable}

*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` {#get-data-usage--data-uplinkbytesbillable}

*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` {#get-data-usage--data-billablebytestotal}

*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` {#get-data-usage--downlinkpackets}

*integer (optional)*

The number of packets received by a device. This field is only present when the `type` is `"satellite"`.

### `uplink_packets` {#get-data-usage--uplinkpackets}

*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-events-usage}

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 <token>`, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). |

Arguments

### `period` {#get-events-usage--period}

*string (required)*

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

### `startDate` {#get-events-usage--startdate}

*integer (optional)*

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

### `endDate` {#get-events-usage--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` {#get-events-usage--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` {#get-events-usage--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` {#get-events-usage--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` {#get-events-usage--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` {#get-events-usage--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` {#get-events-usage--includenotefiles}

*boolean (optional, default to `false`)*

When true, includes per-Notefile event counts in the response.

### `limit` {#get-events-usage--limit}

*integer (optional)*

The maximum number of data points to return.

**Basic**

**Bash**

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

**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";
let period = "day";

apiInstance.getEventsUsage(projectOrProductUID, period).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data),
    );
  },
  (error) => {
    console.error(error);
  },
);
```

**Python**

```python
import os
from pprint import pprint

import notehub_py

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:
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8"
    period = "day"

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

**Optional Params**

**Bash**

```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>&notefile=<notefile>&skipRecentData=<skipRecentData>&includeNotefiles=<includeNotefiles>'
   -H 'Authorization: Bearer <access_token>'
```

**Response Members**

### `truncated` {#get-events-usage--truncated}

*boolean*

Whether the results were truncated based on the provided arguments.

### `data` {#get-events-usage--data}

*array of objects*

An array of objects with event-usage data. Each object may contain the following fields:

### `data.device` {#get-events-usage--data-device}

*string (optional)*

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

### `data.fleet` {#get-events-usage--data-fleet}

*string (optional)*

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

### `data.notefiles` {#get-events-usage--data-notefiles}

*object (optional)*

An object containing Notefile-specific usage data (only present when `includeNotefiles=true` is specified).

### `data.period` {#get-events-usage--data-period}

*string (date)*

The time period for this usage aggregation.

### `data.platform_events` {#get-events-usage--data-platformevents}

*integer*

The number of [platform events](https://dev.blues.io/api-reference/glossary.md#platform-event) recorded during the specified period.

### `data.total_events` {#get-events-usage--data-totalevents}

*integer*

The total number of events recorded during the specified period.

### `data.billable_events` {#get-events-usage--data-billableevents}

*integer*

The total number of billable events.

### `data.watchdog_events` {#get-events-usage--data-watchdogevents}

*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` {#get-events-usage--data-totaldevices}

*integer*

The total number of devices in the specified period and aggregation.

### `data.total_days_in_period` {#get-events-usage--data-totaldaysinperiod}

*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` {#get-events-usage--data-totalfwupdates}

*integer*

The number of firmware updates in the specified period.

### `data.total_reboots` {#get-events-usage--data-totalreboots}

*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}

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 <token>`, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). |

Arguments

### `period` {#get-route-usage--period}

*string (required)*

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

### `startDate` {#get-route-usage--startdate}

*integer (optional)*

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

### `endDate` {#get-route-usage--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` {#get-route-usage--routeuid}

*Array (optional)*

An [array](https://dev.blues.io/api-reference/notehub-api.md#using-array-arguments) of RouteUID to filter by.

### `aggregate` {#get-route-usage--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` {#get-route-usage--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` {#get-route-usage--limit}

*integer (optional)*

The maximum number of data points to return.

**Basic**

**Bash**

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

**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";
let period = "day";

apiInstance.getRouteLogsUsage(projectOrProductUID, period).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data),
    );
  },
  (error) => {
    console.error(error);
  },
);
```

**Python**

```python
import os
from pprint import pprint

import notehub_py

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:
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8"
    period = "day"

    try:
        api_response = api_instance.get_route_logs_usage(
            project_or_product_uid, period
        )
        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)
```

**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);
});
```

**Response Members**

### `truncated` {#get-route-usage--truncated}

*boolean*

Whether the results were truncated based on the provided arguments.

### `route_logs` {#get-route-usage--routelogs}

*array of objects*

An array of objects with route-usage data. Each object may contain the following fields:

### `route_logs.route` {#get-route-usage--routelogs-route}

*string*

The RouteUID of the current usage aggregation. (Only in response when `"aggregate"` is set to `"route"`.)

### `route_logs.period` {#get-route-usage--routelogs-period}

*string (date)*

The time period for this usage aggregation.

### `route_logs.failed_routes` {#get-route-usage--routelogs-failedroutes}

*integer*

The number of failed route executions during the specified period.

### `route_logs.successful_routes` {#get-route-usage--routelogs-successfulroutes}

*integer*

The number of successful route executions during the specified period.

### `route_logs.total_routes` {#get-route-usage--routelogs-totalroutes}

*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-sessions-usage}

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 <token>`, where the token is a valid [authentication token](https://dev.blues.io/api-reference/notehub-api.md#authentication). |

Arguments

### `period` {#get-sessions-usage--period}

*string (required)*

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

### `startDate` {#get-sessions-usage--startdate}

*integer (optional)*

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

### `endDate` {#get-sessions-usage--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` {#get-sessions-usage--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` {#get-sessions-usage--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` {#get-sessions-usage--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` {#get-sessions-usage--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` {#get-sessions-usage--limit}

*integer (optional)*

The maximum number of data points to return.

**Basic**

**Bash**

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

**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";
let period = "day";

apiInstance.getSessionsUsage(projectOrProductUID, period).then(
  (data) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data),
    );
  },
  (error) => {
    console.error(error);
  },
);
```

**Python**

```python
import os
from pprint import pprint

import notehub_py

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:
    api_instance = notehub_py.UsageApi(api_client)
    project_or_product_uid = "app:2606f411-dea6-44a0-9743-1130f57d77d8"
    period = "day"

    try:
        api_response = api_instance.get_sessions_usage(
            project_or_product_uid, period
        )
        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/<projectOrProductUID>/usage/sessions?period=<period>&startDate=<startDate>&endDate=<endDate>&deviceUID=<deviceUID>&fleetUID=<fleetUID>&aggregate=<aggregate>&skipRecentData=<skipRecentData>'
   -H 'Authorization: Bearer <access_token>'
```

**Response Members**

### `truncated` {#get-sessions-usage--truncated}

*boolean*

Whether the results were truncated based on the provided arguments.

### `sessions` {#get-sessions-usage--sessions}

*array of objects*

An array of objects with session-usage data. Each object may contain the following fields:

### `sessions.device` {#get-sessions-usage--sessions-device}

*string (optional)*

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

### `sessions.fleet` {#get-sessions-usage--sessions-fleet}

*string (optional)*

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

### `sessions.period` {#get-sessions-usage--sessions-period}

*string (date)*

The time period for this usage aggregation.

### `sessions.sessions` {#get-sessions-usage--sessions-sessions}

*integer*

The number of sessions recorded during the specified period.

### `sessions.total_bytes` {#get-sessions-usage--sessions-totalbytes}

*integer*

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

### `sessions.total_devices` {#get-sessions-usage--sessions-totaldevices}

*integer*

The total number of devices in the specified period and aggregation.

### `sessions.first_sync_sessions` {#get-sessions-usage--sessions-firstsyncsessions}

*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` {#get-sessions-usage--sessions-sessionsbytransport}

`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")

Can we improve this page? [Send us feedback](mailto:devrel@blues.com)
