Device Statistics

Retrieve device counts and status distribution metrics

Get Device Statistics

Retrieve device statistics including total count and distribution across all status types. Supports filtering by DMS, tags, metadata, creation time, and other device fields.

Important: Filtering by status is not permitted on this endpoint. The API always returns the status distribution for all devices matching the other filter criteria.

Query Parameters

filter · string

Filter expression to narrow statistics scope. Supports all device filter fields except status:

• id - Device identifier
• dms_owner - DMS identifier
• tags - Device tags
• creation_timestamp - Device creation time
• metadata - Device metadata (using JSONPath)

See filtering examples below.

Response

total · integer

Total number of devices matching the filter criteria

status_distribution · object

Device count for each status type. Keys are status values:

NO_IDENTITY · integer

Devices with no identity assigned

ACTIVE · integer

Active devices

RENEWAL_WINDOW · integer

Devices in certificate renewal window

ABOUT_TO_EXPIRE · integer

Devices with certificates about to expire

EXPIRED · integer

Devices with expired certificates

REVOKED · integer

Devices with revoked certificates

DECOMMISSIONED · integer

Decommissioned devices

Example: All Devices

Get statistics for all devices in the system:

curl -X GET "https://your-instance.com/api/devmanager/v1/stats" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "total": 150,
  "status_distribution": {
    "NO_IDENTITY": 10,
    "ACTIVE": 100,
    "RENEWAL_WINDOW": 15,
    "ABOUT_TO_EXPIRE": 5,
    "EXPIRED": 8,
    "REVOKED": 7,
    "DECOMMISSIONED": 5
  }
}

---

Filtering Examples

Filter by DMS

Get statistics for devices managed by a specific DMS:

curl "https://your-instance.com/api/devmanager/v1/stats?filter=dms_owner[eq]:dms-production" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Filter by Tag

Get statistics for devices with a specific tag:

# Case-sensitive tag search
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:production" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Case-insensitive tag search
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains_ic]:PRODUCTION" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Filter by Creation Date

Get statistics for devices created after a specific date:

curl "https://your-instance.com/api/devmanager/v1/stats?filter=creation_timestamp[af]:2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get statistics for devices created in a date range:

# Devices created after Jan 1, 2024 and before Mar 1, 2026
curl "https://your-instance.com/api/devmanager/v1/stats?filter=creation_timestamp[af]:2024-01-01T00:00:00Z&filter=creation_timestamp[bf]:2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Multiple Filters

Combine multiple filters to narrow the scope:

# Production devices managed by a specific DMS
curl "https://your-instance.com/api/devmanager/v1/stats?filter=dms_owner[eq]:dms-prod&filter=tags[contains]:production" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Sensors created in the last 30 days
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:sensor&filter=creation_timestamp[af]:2026-02-07T00:00:00Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Filter by Metadata

Use JSONPath to filter by metadata fields:

# Devices in a specific location (metadata)
curl "https://your-instance.com/api/devmanager/v1/stats?filter=metadata[jsonpath]:$.location[?(@=='warehouse-a')]" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Use Cases

Monitor Certificate Health

Identify devices requiring attention based on certificate status:

# Get overall certificate health
curl "https://your-instance.com/api/devmanager/v1/stats" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example response showing certificate issues:

{
  "total": 500,
  "status_distribution": {
    "NO_IDENTITY": 5,
    "ACTIVE": 450,
    "RENEWAL_WINDOW": 20,
    "ABOUT_TO_EXPIRE": 10,
    "EXPIRED": 8,
    "REVOKED": 5,
    "DECOMMISSIONED": 2
  }
}

This shows:

• 20 devices in renewal window (action recommended)
• 10 devices about to expire (urgent action needed)
• 8 devices with expired certificates (immediate action required)

DMS Capacity Planning

Get device count per DMS to balance load:

# Statistics for DMS 1
curl "https://your-instance.com/api/devmanager/v1/stats?filter=dms_owner[eq]:dms-1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Statistics for DMS 2
curl "https://your-instance.com/api/devmanager/v1/stats?filter=dms_owner[eq]:dms-2" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Environment-Specific Metrics

Track device health across different environments:

# Production environment
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:production" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Staging environment
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:staging" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Development environment
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:development" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Device Type Analysis

Break down statistics by device type:

# Sensor statistics
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:sensor" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Gateway statistics
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:gateway" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Controller statistics
curl "https://your-instance.com/api/devmanager/v1/stats?filter=tags[contains]:controller" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Error Responses

Invalid Filter

Attempting to filter by status returns a 400 Bad Request:

# This will fail
curl "https://your-instance.com/api/devmanager/v1/stats?filter=status[eq]:ACTIVE" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "err": "filtering by status is not permitted on stats endpoint"
}

Invalid Field

Using an invalid filter field returns a 400 Bad Request:

{
  "err": "invalid filter field 'invalid_field'"
}

---

Related Endpoints

Device Group Statistics

Get statistics for a specific device group

List Devices

Retrieve individual device records

Notes

When no filters are provided, the endpoint returns statistics for all devices in the system.

The status field cannot be used as a filter on this endpoint. To get devices with a specific status, use the List Devices endpoint with a status filter.