Back to Docs

Asset Utilization

The Asset Utilization API lets you track when and where assets are being used across your facilities: monitor usage patterns, optimize allocation, identify underutilized equipment, and generate reports.

Before You Begin

An access token. See Authentication.

Query Asset Utilization

GET {{API_DOMAIN}}/integrations/asset-utilization-lite/

Retrieve utilization events for assets, filtered by customer reference, time range, or location attributes.

Query Parameters

Parameter	Type	Location	Required	Description
`customer_reference`	string	query	No	Filter by your equipment ID
`start_date__gte`	string	query	No	Utilization start date (ISO8601), greater than or equal
`start_date__lte`	string	query	No	Utilization start date (ISO8601), less than or equal
`end_date__gte`	string	query	No	Utilization end date (ISO8601), greater than or equal
`end_date__lte`	string	query	No	Utilization end date (ISO8601), less than or equal
`campus_id`	string	query	No	Filter by campus identifier
`building_id`	string	query	No	Filter by building identifier
`floor_id`	string	query	No	Filter by floor identifier
`room_id`	string	query	No	Filter by room identifier

Example Request

bash

curl -sS "{{API_DOMAIN}}/integrations/asset-utilization-lite/?customer_reference=SRC-FR-01" \
  -H "Authorization: Bearer $MQ_TOKEN" | jq

Example Response

json

{
  "id": 22550,
  "customer_reference": "SRC-FR-01",
  "asset_description": "-20 Freezer",
  "asset_device": [
    { "device_id": "D4DA38FFFF6FBEF2" },
    { "device_id": "24E124601E283419" }
  ],
  "campus_description": "Comcast Philadelphia Campus",
  "campus_id": "phila",
  "building_description": "Comcast Center",
  "building_id": "CC",
  "floor_description": "35",
  "floor_id": "CC_35",
  "room_description": "Demo",
  "room_id": "Demo",
  "zone_description": "Demo_1",
  "local_timezone": "America/New_York",
  "start_date": "2025-09-05T14:42:37Z",
  "end_date": null,
  "is_utilization": true
}

Understanding the Response

When end_date is null and is_utilization is true, the asset is currently in use:

json

{
  "start_date": "2025-09-05T14:42:37Z",
  "end_date": null,
  "is_utilization": true
}

When both dates are set, the utilization period has ended:

json

{
  "start_date": "2025-09-05T14:42:37Z",
  "end_date": "2025-09-05T16:30:15Z",
  "is_utilization": false
}

Time Range Queries

code

# A specific month
GET {{API_DOMAIN}}/integrations/asset-utilization-lite/?start_date__gte=2025-08-01T00:00:00Z&start_date__lte=2025-08-31T23:59:59Z

# Currently active utilizations
GET {{API_DOMAIN}}/integrations/asset-utilization-lite/?end_date__isnull=true

# A specific location
GET {{API_DOMAIN}}/integrations/asset-utilization-lite/?building_id=CC&floor_id=35

Response Codes

Code	Status	Description
200	OK	Utilization data retrieved successfully
400	Bad Request	Invalid query parameters
401	Unauthorized	Invalid or expired access token
404	Not Found	No records matched the filter criteria
5xx	Internal Server Error	Service temporarily unavailable

Calculating Utilization Metrics

To calculate utilization percentage:

Query all utilization events for a time period.
Sum the duration of each event (end_date - start_date).
Divide by total available time.
Multiply by 100 for percentage.

python

total_hours = sum(
    (event.end_date - event.start_date).total_hours
    for event in events if event.end_date
)
utilization_percent = (total_hours / (24 * 30)) * 100

What's Next?

Sensor Data: Query readings across 40+ sensor types.
Site Health: Instance-wide and per-building connectivity health.

Sensor Data Site Health