Liveness
GET/api/v1/liveness
Authorization
bearer_token In: header
Query Parameters
Only return entities whose uptime over the window is below this percentage
doubleUptime window in seconds (defaults to 24 hours)
int640 <= valueOnly return entities currently alive (true) or dead (false)
Maximum number of entities to return
0 <= valueResponse Body
application/json
curl -X GET "https://example.com/api/v1/liveness"{ "entities": [ { "alive": true, "entity_id": "string", "last_seen_ms": 0, "uptime": 0.1 } ], "total_matched": 0}POST/api/v1/liveness
Records a heartbeat sample (and a latency sample when a client timestamp is supplied) into the entity's Redis TimeSeries, refreshes its latest-metadata document, and returns the entity's full current status. Typically called periodically by IoT devices, services, or game servers.
Authorization
bearer_token In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Entity liveness payload containing entity identification and optional metadata
Response Body
application/json
curl -X POST "https://example.com/api/v1/liveness" \ -H "Content-Type: application/json" \ -d '{ "entity_id": "string" }'{ "alive": true, "client_timestamp_ms": 0, "entity_id": "string", "network_delay_ms": 0, "server_timestamp_ms": 0}GET/api/v1/liveness/{entity_id}
Returns whether the entity is alive within the configured grace window, last-seen timestamps, the latest latency sample, attached labels, and a rolling uptime/latency summary derived from the entity's TimeSeries.
Authorization
bearer_token In: header
Path Parameters
Unique identifier of the entity to check
Response Body
application/json
curl -X GET "https://example.com/api/v1/liveness/device_001"{ "alive": true, "entity_id": "string", "labels": { "property1": "string", "property2": "string" }, "last_seen_client_ms": 0, "last_seen_server_ms": 0, "latency_ms": 0, "metadata": {}, "network_delay_ms": 0, "summary": null}DELETE/api/v1/liveness/{entity_id}
Authorization
bearer_token In: header
Path Parameters
Unique identifier of the entity to delete
Response Body
curl -X DELETE "https://example.com/api/v1/liveness/device_001"GET/api/v1/liveness/{entity_id}/aggregations
Authorization
bearer_token In: header
Path Parameters
Unique identifier of the entity
Query Parameters
Lookback range in seconds (defaults to 24 hours)
int640 <= valueAggregation bucket size in seconds (defaults to 1 hour)
int640 <= valueAggregation function: avg, sum, min, max, count, first, last, range, std.p
Which series to aggregate: latency or heartbeat
Response Body
application/json
curl -X GET "https://example.com/api/v1/liveness/device_001/aggregations"{ "aggregation": "string", "bucket_ms": 0, "data": [ { "timestamp_ms": 0, "value": 0.1 } ], "entity_id": "string", "series": "string"}GET/api/v1/liveness/{entity_id}/history
Authorization
bearer_token In: header
Path Parameters
Unique identifier of the entity
Query Parameters
Window start as Unix timestamp in seconds (defaults to 1 hour ago)
int640 <= valueWindow end as Unix timestamp in seconds (defaults to now)
int640 <= valueMaximum number of samples to return
0 <= valueResponse Body
application/json
curl -X GET "https://example.com/api/v1/liveness/device_001/history"{ "entity_id": "string", "has_more": true, "samples": [ { "latency_ms": 0, "timestamp_ms": 0 } ], "total_in_range": 0}GET/api/v1/liveness/{entity_id}/latency
Authorization
bearer_token In: header
Path Parameters
Unique identifier of the entity
Query Parameters
Lookback range in seconds (defaults to 24 hours)
int640 <= valueTrend bucket size in seconds (defaults to 1 hour)
int640 <= valueResponse Body
application/json
curl -X GET "https://example.com/api/v1/liveness/device_001/latency"{ "current_ms": 0, "entity_id": "string", "stats": { "avg": 0, "max": 0, "min": 0, "std_dev": 0 }, "trend": [ { "avg": 0.1, "timestamp_ms": 0 } ]}GET/api/v1/liveness/{entity_id}/uptime
Authorization
bearer_token In: header
Path Parameters
Unique identifier of the entity
Query Parameters
Comma-separated windows such as 1h,24h,7d
Response Body
application/json
curl -X GET "https://example.com/api/v1/liveness/device_001/uptime"{ "entity_id": "string", "uptime": { "property1": { "downtime_seconds": 0, "outages": 0, "percentage": 0.1 }, "property2": { "downtime_seconds": 0, "outages": 0, "percentage": 0.1 } }}