Usage Report

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": <float>,
    }, ...
  ]
}

• 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</code>: <code class="dcode">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</cod> 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"}'