Device Summary

GET /clients/{client_id}/devices/summary

Returns aggregate statistics about the device fleet for a client organization. Use this endpoint to power dashboard overview cards -- total device count, agent version distribution, and deployment error counts.

This is a point-in-time snapshot, not a time-series. For historical activity trends, see Device Activity.

Path Parameters

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

Response

Returns a DeviceSummary object.

Example Request

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices/summary" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "total_devices": 142,
  "agent_versions": {
    "distinct_count": 3,
    "versions": ["1.2.3", "1.2.2", "1.1.0"]
  },
  "deployment_errors": {
    "total_errors": 7,
    "affected_devices": 4
  }
}

DeviceSummary

Field	Type	Description
total_devices	number	Total number of devices registered for this client
agent_versions	object	Agent version distribution across the fleet
agent_versions.distinct_count	number	Number of distinct agent versions currently deployed
agent_versions.versions	string[]	List of distinct agent version strings
deployment_errors	object	Deployment error summary
deployment_errors.total_errors	number	Total number of deployment errors across all devices
deployment_errors.affected_devices	number	Number of devices that have at least one deployment error

Error Responses

Status	Description
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• List Devices -- Paginated list of all devices
• Get Device -- Full device detail by ID
• Device Activity -- Daily activity time-series for a device