Usage Report

The Usage API offers a few different routes for aggregating device usage data across the devices for the org. It is highly encouraged to use the newer <code class="dcode">v2</code> routes, as these routes are better supported for the future. The <code class="dcode">v1</code> routes are legacy and not as well-supported or maintained.

Device Usage Routes (v2)

The V2 routes described below can be used to generate reports of different types.

Currently, the supported groupings are:

• <code class="dcode">org:</code> Aggregate the device usage for the whole organization in the time bucket. (This is equivalent to: /v2/usage.)
• <code class="dcode">device:</code> Aggregate the device usage for each device in the time bucket.
• <code class="dcode">team:</code> Aggregate the device usage by team in the time bucket.
• <code class="dcode">device_team</code> (or <code class="dcode">device-team</code>): Aggregate the device usage by device, then team for each time bucket.
• <code class="dcode">team/device</code> is equivalent for backward-compatibility.
• <code class="dcode">user:</code> Aggregate the device usage by user in the time bucket.
• <code class="dcode">device_user</code> (or <code class="dcode">device-user</code>): Aggregate the device usage by device, then user for each time bucket.
• <code class="dcode">user/device</code> is equivalent for backward-compatibility.
• <code class="dcode">host:</code> Aggregate the device usage by host in the time bucket.

Query/Body Parameters

These device usage aggregation routes accept the following parameter inputs:

• [1]: Multiple filters can be simultaneously passed, in which case all of the filter types are AND'd together (i.e. will process usage events that match all filters).
• [2]: When the same filter keyword is passed multiple times with different values, the filter type will OR them together (i.e. permit any of these values for this filter type).

Example

To get all of the device usage for the org by device since January 1, 2025, run:

curl -H "Authorization: Bearer {api_token}" "https://api-dev.headspin.io/v2/usage/device?start_date=2025-01-01"

Alternatively, a <code class="dcode">POST</code> request can be made (useful if there are many arguments to pass) passing arguments using the <code class="dcode">application/x-www-form-urlencoded</code> content type:

curl -H "Authorization: Bearer {api_token}" "https://api-dev.headspin.io/v2/usage/device" --data "start_date=2025-01-01"

Sample output (formatting of JSON may vary):

{
  "report": [
    {
      "datetime": "2025-01-01 00:00:00",
      "start_time": "2025-01-01 00:00:00",
      "end_time": "2025-02-01 00:00:00",
      "total_time": 274974.11999845505,
      "device_count": 1,
      "device_address": "<device_addr>",
      "unit": "second"
    },
    {
      "datetime": "2025-02-01 00:00:00",
      "start_time": "2025-02-01 00:00:00",
      "end_time": "2025-03-01 00:00:00",
      "total_time": 668.2219998836517,
      "device_count": 1,
      "device_address": "<device_addr>",
      "unit": "second"
    }
  ]
}

Each entry in the report corresponds to a single bucket (as determined by the grouping) over a single interval. The report may have different fields and values, obviously, depending on the passed parameters.

NOTE: The <code class="dcode">total_time</code> returned in the device usage is across all of the devices reported in the bucket. Thus, to estimate the total time used per device, divide the total by the <code class="dcode">device_count</code>.

Legacy Usage Routes

NOTE: These routes are deprecated and not well-supported at this time!

The Usage API offers the following routes for usage data and statistics retrieval. Note that we adopted a new model that logs the user token after Aug 2022. Before this change, a device session is either associated with a user or a team, hence the <code class="dcode">[total usage]</code> is always the sum of <code class="dcode">[usage by teams] + [usage by users]</code>. In the current scheme, <code class="dcode">[total usage] = [usage by teams] = [usage by users]</code>.

Calculate Aggregated Usage Statistics

We provide several usage statistics that can be grouped by device, device model, user, team, host, or region via the usage API routes. You may find the configurable query parameters here.

Example Request

• Get the total device usage time per day in a date range.

curl -X GET -H "Authorization: Bearer <your_api_token>" "https://api-dev.headspin.io/v1/usage?start_date=20230301&end_date=20230331&metric=total_time&timezone=US/Pacific&bin_size=day&display_all=false" 

• Example response

{"report":
  [
    {
      "datetime": "YYYY-MM-DD",
      "total_time": <float>,
      "unit": "hour",
    }, ...
  ]
}

• Evaluate the average session length for each team on a weekly timescale in a date range.

curl -X GET -H "Authorization: Bearer <your_api_token>" "https://api-dev.headspin.io/v1/usage/team?start_date=20230301&end_date=20230331&metric=total_time&timezone=US/Pacific&bin_size=day"

• Example response

{"report":
  [
    {
      "datetime": "YYYY-MM-DD",
      "team": <team name>,
      "unit": "minute",
      "avg_session_length": ,
    }, ...
  ]
}

• Get device usage for specific teams and device address

curl -X GET -H "Authorization: Bearer <your_api_token>" "https://api-dev.headspin.io/v1/usage/team/device?start_date=20230301&end_date=20230331&metric=total_time&timezone=US/Pacific&bin_size=month&display_all=false&filter_on.team_name=team_1_to_include&filter_on.team_name=team2%20to%20include&filter_on.device_address=device_id@hostname"

Query Parameters

All usage aggregation routes accept the following keywords:

Supported Usage Metrics

*note: The total time unit is shown in minutes only when <code class="dcode">bin_size = 'hour'</code>.

Supported Filtering Keywords

Get A List of Device Usage Events

Individual usage events before any data aggregation may be retrieved via the route <code class="dcode">/v0/usage/events</code>.

A JSON body should be included that has the following shape:

{
 "start_date": "<date>",
 "end_date": "<date>",
 "devices": [<device_address> ...],
 "format": "<format>",
}

Where <code class="dcode">date</code> can have the format <code class="dcode">YYYYMMDD</code> or <code class="dcode">YYYY/MM/DD</code>. <code class="dcode">device_address</code> is a device ID and hostname joined by @, as in <code class="dcode">abcd123@dev-us-mv-0-proxy-2.headspin.io</code>

• <code class="dcode">start_date:</code> The start date from which to gather device usage. Required.
• <code class="dcode">end_date:</code> The end date from which to gather device usage. Optional; this defaults to the current date.
• <code class="dcode">devices:</code> List of device addresses. Optional and defaults to all devices accessible.
• <code class="dcode">format: json</code> or <code class="dcode">csv</code>, the format of the report. Optional; defaults to <code class="dcode">json</code>.

The total range from <code class="dcode">start_date</code> to <code class="dcode">end_date</code> cannot be more than 120 days.

Both the <code class="dcode">json</code> and <code class="dcode">csv</code> output format contain the same information in their respective formats. For <code class="dcode">json</code>, the output is:

{"report":
  [
    {"user": <user name>,
     "email": <email of user>,
     "device_id": <device id>,
     "hostname": <hostname>,
     "start_time": <start date with second resolution>,
     "end_time": <end date with second resolution>,
     "duration": <duration of usage in seconds>,
     "date": <YYYYMMDD date of usage>
    },
    ...
  ]
}

When a device is used in automation mode, instead of <code class="dcode">user</code> and <code class="dcode">email</code>, the usage row will contain <code class="dcode">team</code> and the team name.

The <code class="dcode">csv</code> output will have the same fields as the <code class="dcode">json</code> output with the fields as the titles.

User/Team,Email,Device Id,Hostname,Start time,End time,Duration,Date
...

For an automation team usage the <code class="dcode">Email</code> field will be <code class="dcode">N/A</code>.

Example to get device usage events for the month of June 2020:

curl -X GET -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/usage/events -d '{"start_date": "20200601", "end_date": "20200701"}'