Heartbeats
Heartbeats provide visibility into whether devices and points connected through Mapped are reachable from the Mapped cloud. Use heartbeats to monitor integration health, investigate gaps in timeseries data, and distinguish a problem with an individual entity from a failure in an upstream dependency. Heartbeats only represent reachability that Mapped can determine from its data flow, they cannot confirm a device is operating correctly, that a sensor value is accurate, or a controlled system is performing as expected.
Heartbeat status
A heartbeat is represented as a Point with time-series values. In the current value map:
| Value | State | Meaning |
|---|---|---|
| 0 | OK | Mapped determined that the entity was reachable at the sample timestamp. |
| 1 | NOT_OK | Mapped determined that the entity was not reachable at the sample timestamp. |
Always evaluate the sample timestamp along with its value. An older OK value only describes the entity at the time that sample was recorded.
A missing heartbeat, a stale heartbeat, and an explicit NOT_OK heartbeat are different conditions:
- Missing heartbeat: No heartbeat relationship or sample is available. Reachability is unknown.
- Stale heartbeat: A heartbeat exists, but its most recent sample is older than expected. Reachability is unknown until a new sample is received.
- NOT_OK heartbeat: Mapped received or derived a current signal indicating that the entity is unreachable.
The expected update interval can vary by connector and integration. Consumers should not assume a universal heartbeat interval unless one is defined for the connector they are using.
Scope
Each heartbeat has a scope: the entity or group of entities whose reachability can be determined from a single signal. Depending on the connector and system topology, one heartbeat may apply to:
- One Thing
- One Point
- A network or subsystem
For example, if Mapped can determine that a BACnet network is unreachable, a single heartbeat may describe reachability for the devices on that network. Those devices and their Points can reference the shared heartbeat rather than requiring a separate connectivity signal for every entity.
Scope is connector-dependent. Mapped creates heartbeat relationships only when reachability can be determined reliably from the available data flow.
Direct and upstream heartbeats
There may be several dependencies between Mapped and the entity being monitored. A Point could depend on a device, a gateway, a local network, and a Mapped connector.
Mapped distinguishes between two heartbeat relationships:
- hasHeartbeat identifies the heartbeat directly associated with the Thing or Point.
- upstreamHeartbeat identifies a heartbeat associated with a dependency upstream of that entity.
For example, a temperature Point may have its own heartbeat, while its upstreamHeartbeat represents the gateway used to reach it. If the gateway becomes unreachable, the upstream heartbeat helps explain why the Point cannot be reached even when there is no Point-specific failure.
When troubleshooting, check the direct heartbeat first and then inspect any upstream heartbeat:
| Direct heartbeat | Upstream heartbeat | Interpretation |
|---|---|---|
| OK | OK | The entity and its monitored dependency are reachable. |
| NOT_OK | OK | The failure is likely specific to the entity or its local communication path. |
| NOT_OK or missing | NOT_OK | An upstream dependency may be preventing Mapped from reaching the entity. |
| Missing or stale | OK | Mapped cannot currently determine the entity's direct status. Do not infer that it is healthy. |
These interpretations are diagnostic guidance, not a replacement for connector-specific troubleshooting.
When upstreamHeartbeat is available for an entity, it can be retrieved using the same Point fields as hasHeartbeat:
upstreamHeartbeat {
id
name
valueMap
series(latest: true) {
timestamp
value {
int32Value
}
}
}
Retrieve heartbeats with the API
You can retrieve a heartbeat at the Thing level to confirm that a device is reachable. You can also retrieve heartbeats for the Points associated with that Thing.
The following query retrieves a Thing, its direct heartbeat, and the direct heartbeat associated with each of its Points:
{
things(filter: {id: {eq: "THG7aLjBw5u2YqMCb21iMABCD"}}) {
id
name
hasHeartbeat {
id
name
valueMap
series(latest: true) {
timestamp
value {
int32Value
}
}
}
points {
id
name
hasHeartbeat {
id
name
valueMap
series(latest: true) {
timestamp
value {
int32Value
}
}
}
}
}
}
An example response looks like this:
{
"data": {
"things": [
{
"id": "THG7aLjBw5u2YqMCb21iMABCD",
"name": "Temperature - cghu2l37ej3g008bnb0g",
"hasHeartbeat": {
"id": "PNTc5MYJtRAjBW1VgCpTsrrE",
"name": "Heartbeat cghu2l37ej3g008bnb0g",
"valueMap": {
"0": "OK",
"1": "NOT_OK"
},
"series": [
{
"timestamp": "2026-08-18T14:54:35.219Z",
"value": {
"int32Value": 0
}
}
]
},
"points": [
{
"id": "PNTJ6wANMkE3xKsuVZ24cbc6h",
"name": "Temperature",
"hasHeartbeat": {
"id": "PNTWVsR1jAcMY5BrtCpJgTrE",
"name": "Heartbeat cghu2l37ej3g008bnb0g",
"valueMap": {
"0": "OK",
"1": "NOT_OK"
},
"series": [
{
"timestamp": "2026-08-18T14:54:35.219Z",
"value": {
"int32Value": 0
}
}
]
}
},
{
"id": "PNT1Aqix77eX1NZdYgXws42b",
"name": "Network Signal Strength",
"hasHeartbeat": {
"id": "PNTRt5gCpMYJcW1VsAjBrrTE",
"name": "Heartbeat cghu2l37ej3g008bnb0g",
"valueMap": {
"0": "OK",
"1": "NOT_OK"
},
"series": [
{
"timestamp": "2026-08-18T14:54:35.219Z",
"value": {
"int32Value": 0
}
}
]
}
},
{
"id": "PNT8rfk32abg4ZQ6JvUBZxR9t",
"name": "Battery Status",
"hasHeartbeat": {
"id": "PNTMYcRt5BWjCp1gAJVsrTrE",
"name": "Heartbeat cghu2l37ej3g008bnb0g",
"valueMap": {
"0": "OK",
"1": "NOT_OK"
},
"series": [
{
"timestamp": "2026-08-18T14:54:35.219Z",
"value": {
"int32Value": 0
}
}
]
}
}
]
}
]
}
}
In this response, the latest Thing-level and Point-level heartbeat values are all 0, which maps to OK. At 2026-08-18T14:54:35.219Z, Mapped considered the device and the listed Points reachable.
The Thing and its Points do not need to reference the same heartbeat Point. Heartbeat IDs can differ when the connector can determine reachability at a more specific scope.
Evaluate freshness
The heartbeat value and timestamp should always be evaluated together:
- Read the latest heartbeat sample.
- Translate the numeric value using valueMap.
- Compare the sample timestamp with the expected update interval for the connector.
- If the sample is older than expected, treat the status as unknown or stale rather than continuing to report the last value as current.
- Check upstreamHeartbeat when available to determine whether a dependency explains the failure.
This prevents a last-known OK sample from being interpreted as proof that an entity is currently reachable.
Important considerations
- Heartbeat availability and scope vary by connector.
- A Thing-level heartbeat usually indicates that the device itself is reachable. Point-level heartbeats provide more specific status when the connector supports it.
- Multiple entities may reference the same heartbeat when one signal determines reachability for the entire scope.
- A heartbeat describes connectivity, not the quality or correctness of the entity's data.
- The absence of a heartbeat does not by itself mean that an entity is unreachable.
- Use upstream heartbeats to identify failures in shared dependencies before investigating individual devices or Points.