Retrieve checks for multiple servers
GET api/servers/-/checks
Retrieves the checks for multiple servers. For each check, both the current status and historical data is returned. You can filter the request using the server hostname, node group names, and node groups IDs. You can also filter using any combination of each of those and the response will filter out any duplicates.
Request syntax
get api/servers/-/checksRequest parameters
The request accepts the following data in JSON format.
| Parameter | Type | Description | Required | Default value |
|---|---|---|---|---|
filter_by_name | String | Filter checks by one or more names, separated by a comma. | No | N/A |
filter_by_status | Integer | Filter checks by one or more statuses, separated by a comma. | No | N/A |
hostnames | String | Filter checks by one or more hostnames, separated by a comma. | No | N/A |
group_names | String | Filter checks by one or more node group names, separated by a comma. All servers in each node group in the list will be included. | No | N/A |
group_ids | Integer | Filter checks by one or more node group IDs, separated by a comma. All servers in each node group in the list will be included. | No | N/A |
Response syntax
{
"request": {
"params": {
"hostnames": "string"
},
"at": "timestamp"
},
"servers" : [
{
"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 |
|---|---|---|
request | Object | The details of the request, including the timestamp it was requested. |
hostname | String | The hostname of the server. |
checks | Object | The details about the check. |
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. |
| 422 | Missing parameters to specify hostnames. | The request didn't specify a hostname filter. Specify at least one filter and try again. |
Examples
Example 1: Retrieve the checks from multiple servers, specified by hostname
This example returns the health check details about the servers with hostnames rdepup0 and rdelog0.
ruby api.rb <customer_code> get "api/servers/-/checks?hostnames=rdepup0,rdelog0"Response
{
"request": {
"params": {
"hostnames": "rdepup0,rdelog0"
},
"at": "2026-10-11T01:36:39Z"
},
"servers": [
{
"hostname": "rdelog0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:36:11Z",
"output": "Keepalive last sent from rdelog0 at 2026-10-10 20:36:11 -0500 CDT",
"last_ok": "2026-10-11T01:36:11Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:51Z"
},
{
"status": 0,
"executed": "2026-10-11T01:36:11Z"
}
]
}
]
},
{
"hostname": "rdepup0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:35:58Z",
"output": "Keepalive last sent from rdepup0 at 2026-10-10 20:35:58 -0500 CDT",
"last_ok": "2026-10-11T01:35:58Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:38Z"
},
{
"status": 0,
"executed": "2026-10-11T01:35:58Z"
}
]
}
]
}
]
}In this response, each server shows only its keepalive check and the last two history entries. The full response includes every check on each server and up to 21 history entries per check.
Example 2: Retrieve the checks from multiple servers, specified by node group name
This example returns the health checks of the servers in the Servers Puppet and Servers Logging node groups. Encode spaces in node group names as %20, and separate the names with a comma. Don't wrap the names in quotes: the quotes are treated as part of the names, no node group matches, and the request returns 422 Missing parameters to specify hostnames.
ruby api.rb <customer_code> get "api/servers/-/checks?group_names=Servers%20Puppet,Servers%20Logging"Response
{
"request": {
"params": {
"group_names": "Servers Puppet,Servers Logging"
},
"at": "2026-10-11T01:36:41Z"
},
"servers": [
{
"hostname": "rdelog0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:36:11Z",
"output": "Keepalive last sent from rdelog0 at 2026-10-10 20:36:11 -0500 CDT",
"last_ok": "2026-10-11T01:36:11Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:51Z"
},
{
"status": 0,
"executed": "2026-10-11T01:36:11Z"
}
]
}
]
},
{
"hostname": "rdepup0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:35:58Z",
"output": "Keepalive last sent from rdepup0 at 2026-10-10 20:35:58 -0500 CDT",
"last_ok": "2026-10-11T01:35:58Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:38Z"
},
{
"status": 0,
"executed": "2026-10-11T01:35:58Z"
}
]
}
]
}
]
}In this response, each server shows only its keepalive check and the last two history entries. The full response includes every check on each server and up to 21 history entries per check.
Example 3: Retrieve the checks from multiple servers, specified by node group ID
This example returns the health checks of the servers in the node groups with IDs 2374 and 2378. These are the same node groups as in Example 2, so the response contains the same servers.
ruby api.rb <customer_code> get "api/servers/-/checks?group_ids=2374,2378"Response
{
"request": {
"params": {
"group_ids": "2374,2378"
},
"at": "2026-10-11T01:36:41Z"
},
"servers": [
{
"hostname": "rdelog0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:36:11Z",
"output": "Keepalive last sent from rdelog0 at 2026-10-10 20:36:11 -0500 CDT",
"last_ok": "2026-10-11T01:36:11Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:51Z"
},
{
"status": 0,
"executed": "2026-10-11T01:36:11Z"
}
]
}
]
},
{
"hostname": "rdepup0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:35:58Z",
"output": "Keepalive last sent from rdepup0 at 2026-10-10 20:35:58 -0500 CDT",
"last_ok": "2026-10-11T01:35:58Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:38Z"
},
{
"status": 0,
"executed": "2026-10-11T01:35:58Z"
}
]
}
]
}
]
}In this response, each server shows only its keepalive check and the last two history entries. The full response includes every check on each server and up to 21 history entries per check.
Example 4: Filter the response for a specific check
This example returns the details of the keepalive check for the rdepup0 and rdelog0 servers.
ruby api.rb <customer_code> get "api/servers/-/checks?hostnames=rdepup0,rdelog0&filter_by_name=keepalive"Response
{
"request": {
"params": {
"hostnames": "rdepup0,rdelog0",
"filter_by_name": "keepalive"
},
"at": "2026-10-11T01:36:42Z"
},
"servers": [
{
"hostname": "rdelog0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:36:11Z",
"output": "Keepalive last sent from rdelog0 at 2026-10-10 20:36:11 -0500 CDT",
"last_ok": "2026-10-11T01:36:11Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:51Z"
},
{
"status": 0,
"executed": "2026-10-11T01:36:11Z"
}
]
}
]
},
{
"hostname": "rdepup0",
"checks": [
{
"name": "keepalive",
"status": 0,
"executed": "2026-10-11T01:35:58Z",
"output": "Keepalive last sent from rdepup0 at 2026-10-10 20:35:58 -0500 CDT",
"last_ok": "2026-10-11T01:35:58Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:38Z"
},
{
"status": 0,
"executed": "2026-10-11T01:35:58Z"
}
]
}
]
}
]
}The history arrays are shortened to the last two entries.
Example 5: Filter the response for multiple checks
This example returns the details of the disk_free and memory_available checks for the servers with hostnames rdepup0 and rdelog0.
ruby api.rb <customer_code> get "api/servers/-/checks?hostnames=rdepup0,rdelog0&filter_by_name=disk_free,memory_available"Response
{
"request": {
"params": {
"hostnames": "rdepup0,rdelog0",
"filter_by_name": "disk_free,memory_available"
},
"at": "2026-10-11T01:36:43Z"
},
"servers": [
{
"hostname": "rdelog0",
"checks": [
{
"name": "memory_available",
"status": 0,
"executed": "2026-10-11T01:36:00Z",
"output": "CheckMem OK - value = 37.71 | system_memory_used=37.71\n",
"last_ok": "2026-10-11T01:36:00Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:00Z"
},
{
"status": 0,
"executed": "2026-10-11T01:36:00Z"
}
]
},
{
"name": "disk_free",
"status": 0,
"executed": "2026-10-11T01:34:52Z",
"output": "DISK OK - free space:\n\n[ OK ] 85% /\n[ OK ] 99% /tmp\n[ OK ] 85% /home\n[ OK ] 85% /var\n[ OK ] 85% /var/log\n| /=85%;20;10;0;100 /tmp=99%;20;10;0;100 /home=85%;20;10;0;100 /var=85%;20;10;0;100 /var/log=85%;20;10;0;100\n",
"last_ok": "2026-10-11T01:34:52Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:29:52Z"
},
{
"status": 0,
"executed": "2026-10-11T01:34:52Z"
}
]
}
]
},
{
"hostname": "rdepup0",
"checks": [
{
"name": "memory_available",
"status": 0,
"executed": "2026-10-11T01:36:00Z",
"output": "CheckMem OK - value = 48.93 | system_memory_used=48.93\n",
"last_ok": "2026-10-11T01:36:00Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:35:00Z"
},
{
"status": 0,
"executed": "2026-10-11T01:36:00Z"
}
]
},
{
"name": "disk_free",
"status": 0,
"executed": "2026-10-11T01:34:52Z",
"output": "DISK OK - free space:\n\n[ OK ] 60% /\n[ OK ] 99% /tmp\n[ OK ] 60% /home\n[ OK ] 60% /var\n[ OK ] 60% /var/log\n| /=60%;20;10;0;100 /tmp=99%;20;10;0;100 /home=60%;20;10;0;100 /var=60%;20;10;0;100 /var/log=60%;20;10;0;100\n",
"last_ok": "2026-10-11T01:34:52Z",
"history": [
{
"status": 0,
"executed": "2026-10-11T01:29:52Z"
},
{
"status": 0,
"executed": "2026-10-11T01:34:52Z"
}
]
}
]
}
]
}The history arrays are shortened to the last two entries.
You can also combine the hostnames, group_names, and group_ids filters in one request. Servers that match more than one filter are returned once.