Retrieve checks for a single node
GET api/nodes/hostname/checks
Retrieves the checks for a single node. For each check, both the current status and historical data is returned.
Request syntax
get api/nodes/<hostname>/checksRequest parameters
The request accepts the following query parameters.
| Parameter | Type | Description | Required | Default value |
|---|---|---|---|---|
filter_by_name | String | Filter checks by one or more check names, separated by a comma. If no check matches, the response returns an empty checks list. | No | N/A |
filter_by_status | String | Filter checks by one or more status codes, separated by a comma: 0 (OK), 1 (Warning), or 2 (Critical). | No | N/A |
Response syntax
{
"hostname": "string",
"checks": [
{
"name": "string",
"status": integer,
"executed": "timestamp",
"output": "string",
"last_ok": "timestamp",
"history": [
{
"status": integer,
"executed": "timestamp"
},
{
"status": integer,
"executed": "timestamp"
}
]
}
]
}Response parameters
If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.
| Field | Type | Description |
|---|---|---|
hostname | String | The hostname of the node. |
checks | Array of objects | The checks run on the node. Each check contains the following fields. |
checks.name | String | The name of the check, for example keepalive or disk_free. |
checks.status | Integer | The status of the most recent run of the check: 0 (OK), 1 (Warning), 2 (Critical), or 3 (Unknown). |
checks.executed | Timestamp | The time the check last ran. |
checks.output | String | The output of the most recent run of the check. |
checks.last_ok | Timestamp | The last time the check returned a status of 0. Returns 1970-01-01T00:00:00Z if the check has never returned OK. |
checks.history | Array of objects | The recent results of the check, oldest first. Each entry contains the status and executed time of one run. Up to 21 entries are returned. |
Errors
The following are errors returned by this API. For a complete list of common errors, see Common errors.
| Code | Message | Cause |
|---|---|---|
| 400 | Validation failed: filter_by_status is invalid | The value for filter_by_status is invalid. Specify an integer and try again. |
| 404 | 404 Not Found | No node exists with the specified hostname. The message is returned in an error field. |
Examples
Example 1: Retrieve the checks from a single node
This example returns the healthcheck details about the sit0000red0 node.
ruby api.rb <customer_code> get api/nodes/sit0000red0/checksResponse
{
"hostname": "sit0000red0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2024-09-05T15:34:29Z",
"output": "Keepalive last sent from sit0000red0 at 2024-09-05 11:34:29 -0400 EDT",
"last_ok": "2024-09-05T15:34:29Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T15:34:09Z"
},
{
"status": 0,
"executed": "2024-09-05T15:34:29Z"
}
]
},
{
"name": "cpu_utilization",
"status": 0,
"executed": "2024-09-05T15:34:21Z",
"output": "OK - load average: 0.06, 0.08, 0.08|load1=0.061;0.600;1.000;0; load5=0.081;0.600;1.000;0; load15=0.076;0.600;1.000;0; \n",
"last_ok": "2024-09-05T15:34:21Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T15:34:21Z"
}
]
},
{
"name": "memory_available",
"status": 0,
"executed": "2024-09-05T15:33:57Z",
"output": "CheckMem OK - value = 3.48 | system_memory_used=3.48\n",
"last_ok": "2024-09-05T15:33:57Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T15:33:57Z"
}
]
},
{
"name": "ssh_server",
"status": 0,
"executed": "2024-09-05T15:30:10Z",
"output": "SSH OK - OpenSSH_6.7p1 Debian-5+deb8u8 (protocol 2.0) | time=0.012457s;;;0.000000;10.000000\n",
"last_ok": "2024-09-05T15:30:10Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T15:30:10Z"
}
]
},
{
"name": "disk_free",
"status": 0,
"executed": "2024-09-05T15:30:04Z",
"output": "DISK OK - free space:\n\n[ OK ] 94% /\n[ OK ] 100% /tmp\n[ OK ] 94% /home\n[ OK ] 94% /var\n[ OK ] 94% /var/log\n| /=94%;20;10;0;100 /tmp=100%;20;10;0;100 /home=94%;20;10;0;100 /var=94%;20;10;0;100 /var/log=94%;20;10;0;100\n",
"last_ok": "2024-09-05T15:30:04Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T15:30:04Z"
}
]
},
{
"name": "fs_writable",
"status": 0,
"executed": "2024-09-05T15:29:48Z",
"output": "Filesystem OK\n\nOK - / Filesystem is writable\n",
"last_ok": "2024-09-05T15:29:48Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T15:29:48Z"
}
]
},
{
"name": "puppet_client",
"status": 0,
"executed": "2024-09-05T15:16:53Z",
"output": "OK\n",
"last_ok": "2024-09-05T15:16:53Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T15:16:53Z"
}
]
},
{
"name": "puppet_errors",
"status": 0,
"executed": "2024-09-05T14:59:20Z",
"output": "OK: Puppet last run had 0 failures\n",
"last_ok": "2024-09-05T14:59:20Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T14:59:20Z"
}
]
}
]
}Example 2: Filter the response for a specific check
This example returns the details of the keepalive check for the sit0000red0 node.
ruby api.rb <customer_code> get "api/nodes/sit0000red0/checks?filter_by_name=keepalive"Response
{
"hostname": "sit0000red0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2024-09-05T16:58:29Z",
"output": "Keepalive last sent from sit0000red0 at 2024-09-05 12:58:29 -0400 EDT",
"last_ok": "2024-09-05T16:58:29Z",
"history": [
{
"status": 0,
"executed": "2024-09-05T16:58:09Z"
},
{
"status": 0,
"executed": "2024-09-05T16:58:29Z"
}
]
}
]
}Example 3: Filter the response for multiple checks
This example returns the details of the cpu_utilization and memory_available checks for the sit0000red0 node.
ruby api.rb <customer_code> get "api/nodes/sit0000red0/checks?filter_by_name=cpu_utilization,memory_available"The response uses the same format as Example 2 and includes only the cpu_utilization and memory_available checks.
Example 4: Filter the response for checks with a warning or critical status
This example returns the checks with status 1 (Warning) or 2 (Critical) for the sit0000red0 node. In this response, the history arrays are shortened for readability.
ruby api.rb <customer_code> get "api/nodes/sit0000red0/checks?filter_by_status=1,2"Response
{
"hostname": "sit0000red0",
"checks": [
{
"name": "corosync_resources",
"status": 2,
"executed": "2026-10-10T23:42:23Z",
"output": "CRITICAL: The resource(s) fence_sit0000red0 lvm-additional-kvm_backups-resource:1 drbd-additional-kvm_backups-resource check_eno4 down\n",
"last_ok": "1970-01-01T00:00:00Z",
"history": [
{
"status": 2,
"executed": "2026-10-10T23:40:23Z"
},
{
"status": 2,
"executed": "2026-10-10T23:42:23Z"
}
]
},
{
"name": "corosync_node",
"status": 1,
"executed": "2026-10-10T23:41:38Z",
"output": "WARNING: The node(s) sit0000red1 down\n",
"last_ok": "1970-01-01T00:00:00Z",
"history": [
{
"status": 1,
"executed": "2026-10-10T23:39:38Z"
},
{
"status": 1,
"executed": "2026-10-10T23:41:38Z"
}
]
},
{
"name": "drbd",
"status": 2,
"executed": "2026-10-10T23:41:13Z",
"output": "DRBD CRITICAL: Device 99 WFConnection UpToDate\n",
"last_ok": "2025-10-17T20:23:19Z",
"history": [
{
"status": 2,
"executed": "2026-10-10T23:39:13Z"
},
{
"status": 2,
"executed": "2026-10-10T23:41:13Z"
}
]
},
{
"name": "puppet_errors",
"status": 2,
"executed": "2026-10-10T22:59:19Z",
"output": "CRITICAL: Puppet last run had 1 failures\n",
"last_ok": "2026-10-10T00:59:19Z",
"history": [
{
"status": 2,
"executed": "2026-10-10T21:59:19Z"
},
{
"status": 2,
"executed": "2026-10-10T22:59:19Z"
}
]
}
]
}Example 5: Filter the response for both a specific check and status
This example returns the keepalive and disk_free checks with status 0 or 1 for the sit0000red0 node.
ruby api.rb <customer_code> get "api/nodes/sit0000red0/checks?filter_by_name=keepalive,disk_free&filter_by_status=0,1"The response uses the same format as Example 2 and includes only the matching checks.
Example 6: Filter by a check name that doesn't exist
If no check matches the filter, the API returns HTTP 200 with an empty checks list.
ruby api.rb <customer_code> get "api/nodes/sit0000red0/checks?filter_by_name=not_a_check"Response
{
"hostname": "sit0000red0",
"checks": []
}