Retrieve checks for a server
GET api/servers/hostname/checks
Retrieves the checks for a single server. For each check, both the current status and historical data is returned.
Request syntax
get api/servers/<hostname>/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 |
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 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. |
Examples
Example 1: Retrieve the checks from a single server
This example returns the health check details about the server with hostname rdepup0.
ruby api.rb <customer_code> get "api/servers/rdepup0/checks"Response
{
"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": "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, only the memory_available and keepalive checks and the last two history entries are shown. The full response includes every check on the server, such as disk_free, ssh_server, fs_writable, puppet_client, and puppet_errors, and up to 21 history entries per check.
Example 2: Filter the response for a specific check
This example returns the details of the keepalive check for the rdepup0 server.
ruby api.rb <customer_code> get "api/servers/rdepup0/checks?filter_by_name=keepalive"Response
{
"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 3: Filter the response for multiple checks
This example returns the details of the disk_free and memory_available checks for the rdepup0 server.
ruby api.rb <customer_code> get "api/servers/rdepup0/checks?filter_by_name=disk_free,memory_available"Response
{
"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.
Example 4: Filter the response for a specific status
This example returns the checks with status 0 (OK) for the rdepup0 server.
ruby api.rb <customer_code> get "api/servers/rdepup0/checks?filter_by_status=0"Response
{
"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": "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, only two of the returned checks and the last two history entries are shown. The full response returned six checks. The fs_writable check was left out because its status was 2 (Critical) when the request was made.
Example 5: Filter the response for both a specific check and status
This example returns the keepalive check for the rdepup0 server, but only if its status is 0 (OK).
ruby api.rb <customer_code> get "api/servers/rdepup0/checks?filter_by_name=keepalive&filter_by_status=0"Response
{
"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.