Liveness
GET/api/v1/liveness
Authorization
bearer_token In: header
Query Parameters
Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.
Comma-separated sort keys, - for descending, at most 1. Keys: uptime, last_seen_ms, entity_id. Default: entity_id.
Rows per page, 1 to 100 (default 25).
1 <= value <= 100The page.next_cursor of the previous page. Cannot be combined with page.
A 1-based page number, for jumping. Cannot be combined with cursor.
1 <= valueSet to true to include the number of matching rows in page.total.
Window, in seconds, that each entity's uptime is measured over (defaults to 24 hours)
int640 <= 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 } ], "page": { "has_more": true, "next_cursor": "string", "page": 0, "total": 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
Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.
Comma-separated sort keys, - for descending, at most 1. Keys: timestamp. Default: timestamp.
Rows per page, 1 to 100 (default 25).
1 <= value <= 100The page.next_cursor of the previous page. Cannot be combined with page.
Set to true to include the number of matching rows in page.total.
Response Body
application/json
curl -X GET "https://example.com/api/v1/liveness/device_001/history"{ "entity_id": "string", "page": { "has_more": true, "next_cursor": "string", "page": 0, "total": 0 }, "samples": [ { "latency_ms": 0, "timestamp_ms": 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 } }}