Device Activity

GET /clients/{client_id}/analytics/devices/{device_id}/activity

Returns a daily time-series of activity for a specific device. Supports multiple metrics -- total activity count and distinct user count per day.

Use Case

Use this endpoint to:

• Display device usage trends on the device detail page (line chart, sparkline)
• Track how many users are active on a shared device over time
• Identify underutilized or heavily used devices
• Compare device activity across time periods

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization
device_id	string (uuid)	Unique identifier for the device

Query Parameters

Parameter	Type	Required	Description
granularity	string	Yes	Aggregation granularity: daily, weekly, monthly, quarterly
start_date	string	Yes	Start of date range (YYYY-MM-DD)
end_date	string	Yes	End of date range, inclusive (YYYY-MM-DD)
metric	string	Yes	Metric to retrieve. See Available Metrics.

Available Metrics

Metric	Label	Description	DB Aggregation
activity-count	Total Activity	Sum of all activity events on this device	SUM(heartbeats.total_activity_count) GROUP BY DATE(generated_at_utc) WHERE device_id = ?
user-count	Daily Users	Number of distinct users active on this device per day	COUNT(DISTINCT heartbeats.user_id) GROUP BY DATE(generated_at_utc) WHERE device_id = ?

Response

Returns an ActivityTimeSeries.

Example Requests

Activity count

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890/activity?start_date=2026-01-01&end_date=2026-01-15&metric=activity-count" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

User count

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890/activity?start_date=2026-01-01&end_date=2026-01-15&metric=user-count" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Responses

activity-count

{
  "metric": "activity-count",
  "label": "Total Activity",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-15"
  },
  "data": [
    { "date": "2026-01-01", "value": 87 },
    { "date": "2026-01-02", "value": 64 },
    { "date": "2026-01-03", "value": 92 },
    { "date": "2026-01-04", "value": 0 },
    { "date": "2026-01-05", "value": 0 },
    { "date": "2026-01-06", "value": 78 },
    { "date": "2026-01-07", "value": 81 },
    { "date": "2026-01-08", "value": 95 },
    { "date": "2026-01-09", "value": 73 },
    { "date": "2026-01-10", "value": 88 },
    { "date": "2026-01-11", "value": 0 },
    { "date": "2026-01-12", "value": 0 },
    { "date": "2026-01-13", "value": 91 },
    { "date": "2026-01-14", "value": 85 },
    { "date": "2026-01-15", "value": 79 }
  ]
}

user-count

{
  "metric": "user-count",
  "label": "Daily Users",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-15"
  },
  "data": [
    { "date": "2026-01-01", "value": 3 },
    { "date": "2026-01-02", "value": 2 },
    { "date": "2026-01-03", "value": 3 },
    { "date": "2026-01-04", "value": 0 },
    { "date": "2026-01-05", "value": 0 },
    { "date": "2026-01-06", "value": 3 },
    { "date": "2026-01-07", "value": 2 },
    { "date": "2026-01-08", "value": 3 },
    { "date": "2026-01-09", "value": 2 },
    { "date": "2026-01-10", "value": 3 },
    { "date": "2026-01-11", "value": 0 },
    { "date": "2026-01-12", "value": 0 },
    { "date": "2026-01-13", "value": 3 },
    { "date": "2026-01-14", "value": 2 },
    { "date": "2026-01-15", "value": 3 }
  ]
}

Error Responses

Status	Description
400	Invalid parameters (bad date format, range exceeds 90 days, unknown metric)
401	Authentication required
403	Insufficient permissions for this client
404	Device or client not found
500	Server error

Example Error Response

{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown metric: invalid-metric. Valid values: activity-count, user-count",
    "details": {
      "metric": "invalid-metric"
    }
  }
}

Notes

• The response always includes every date in the range, even weekends or days with zero activity.
• All dates are in the client's configured timezone.
• user-count counts distinct users per day, not cumulative. A user active on 3 days appears in each day's count separately.
• Data freshness depends on heartbeat delivery (typically within 5 minutes).

Related Endpoints

• Get Device -- Device identity and hardware specs
• Device Users -- Users observed on a device
• User Activity -- Activity time-series for a user
• App Activity -- Activity time-series for an app