Port Monitors
Port Monitors
Port monitors let you check TCP ports, UDP connectivity, DNS records, and ICMP ping for any host. Use them to verify that services like SSH, databases, mail servers, and DNS are reachable and responding correctly.
List port monitors
/api/v1/port-monitors
Returns a paginated list of all port monitors in the project associated with your API key.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | — | Filter by status (up, down, paused) |
type | string | — | Filter by monitor type (tcp, udp, dns, icmp) |
per_page | integer | 25 | Results per page |
page | integer | 1 | Page number |
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/port-monitors?type=tcp&per_page=10"
$response = Http::withToken('YOUR_API_KEY') ->get('https://watchcron.com/api/v1/port-monitors', [ 'type' => 'tcp', 'per_page' => 10, ]); $monitors = $response->json('data');
import requests response = requests.get( "https://watchcron.com/api/v1/port-monitors", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"type": "tcp", "per_page": 10}, ) monitors = response.json()["data"]
const response = await fetch( "https://watchcron.com/api/v1/port-monitors?type=tcp&per_page=10", { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: monitors } = await response.json();
req, _ := http.NewRequest("GET", "https://watchcron.com/api/v1/port-monitors?type=tcp&per_page=10", nil) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 200 OK
{
"data": [
{
"uuid": "d4e5f6a7-b8c9-0123-defa-234567890123",
"name": "SSH Server",
"type": "tcp",
"host": "server.example.com",
"port": 22,
"status": "up",
"interval_seconds": 300,
"timeout_seconds": 5,
"dns_record_type": null,
"dns_expected_value": null,
"is_active": true,
"last_checked_at": "2026-10-26T08:15:00Z",
"last_response_time_ms": 45,
"last_error": null,
"last_up_at": "2026-10-26T08:15:00Z",
"last_down_at": null,
"maintenance_windows": [],
"created_at": "2026-06-10T12:00:00Z",
"updated_at": "2026-10-26T08:15:00Z"
}
],
"meta": {
"pagination": {
"total": 18,
"per_page": 10,
"current_page": 1,
"last_page": 2
}
}
}
Port monitor object
Every port monitor response includes these fields:
| Field | Type | Description |
|---|---|---|
uuid | string | Unique identifier (UUID v4). Used in all API URLs. |
name | string | Display name of the monitor |
type | string | Monitor type: tcp, udp, dns, or icmp |
host | string | Hostname or IP address to check |
port | integer|null | Port number (used for tcp and udp types) |
status | string | Current status: up, down, or paused |
interval_seconds | integer | Check interval in seconds (default: 300) |
timeout_seconds | integer | Connection timeout in seconds (default: 5) |
dns_record_type | string|null | DNS record type to query (for dns type only) |
dns_expected_value | string|null | Expected DNS record value (for dns type only) |
is_active | boolean | Whether monitoring is active (not paused) |
last_checked_at | string|null | ISO 8601 timestamp of last check |
last_response_time_ms | integer|null | Response time of last check in milliseconds |
last_error | string|null | Error message from last failed check |
last_up_at | string|null | ISO 8601 timestamp of last successful check |
last_down_at | string|null | ISO 8601 timestamp of last failed check |
maintenance_windows | array | Configured maintenance windows (alerts suppressed during these periods) |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Type values
| Type | Description |
|---|---|
tcp | TCP port check — verifies a TCP connection can be established on the specified port |
udp | UDP connectivity check — sends a UDP packet to the specified port and checks for a response |
dns | DNS record check — queries a DNS record and optionally validates the resolved value |
icmp | ICMP ping — sends an ICMP echo request to verify the host is reachable |
Create a port monitor
/api/v1/port-monitors
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Monitor name (max 255 characters) |
type | string | Yes | tcp, udp, dns, or icmp |
host | string | Yes | Hostname or IP address (max 255 characters) |
port | integer | If tcp/udp | Port number (1–65535). Required for tcp and udp types. |
timeout_seconds | integer | No | Connection timeout in seconds (1–60, default: 5) |
interval_seconds | integer | No | Check interval in seconds (min 30, default: 300) |
dns_record_type | string | No | DNS record type: A, AAAA, MX, CNAME, TXT, etc. (for dns type) |
dns_expected_value | string | No | Expected DNS value to match (max 255 characters, for dns type) |
maintenance_windows | array | No | Maintenance windows during which alerts are suppressed |
port field is required when type is tcp or udp. For dns and icmp types, it is ignored.Example: create a TCP monitor
curl -X POST https://watchcron.com/api/v1/port-monitors \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "SSH Server", "type": "tcp", "host": "server.example.com", "port": 22, "timeout_seconds": 5, "interval_seconds": 300 }'
$response = Http::withToken('YOUR_API_KEY') ->post('https://watchcron.com/api/v1/port-monitors', [ 'name' => 'SSH Server', 'type' => 'tcp', 'host' => 'server.example.com', 'port' => 22, 'timeout_seconds' => 5, 'interval_seconds' => 300, ]); $monitor = $response->json('data');
import requests response = requests.post( "https://watchcron.com/api/v1/port-monitors", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "name": "SSH Server", "type": "tcp", "host": "server.example.com", "port": 22, "timeout_seconds": 5, "interval_seconds": 300, }, ) monitor = response.json()["data"]
const response = await fetch("https://watchcron.com/api/v1/port-monitors", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ name: "SSH Server", type: "tcp", host: "server.example.com", port: 22, timeout_seconds: 5, interval_seconds: 300, }), }); const { data: monitor } = await response.json();
body := strings.NewReader(`{ "name": "SSH Server", "type": "tcp", "host": "server.example.com", "port": 22, "timeout_seconds": 5, "interval_seconds": 300 }`) req, _ := http.NewRequest("POST", "https://watchcron.com/api/v1/port-monitors", body) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 201 Created
{
"data": {
"uuid": "d4e5f6a7-b8c9-0123-defa-234567890123",
"name": "SSH Server",
"type": "tcp",
"host": "server.example.com",
"port": 22,
"status": "up",
"interval_seconds": 300,
"timeout_seconds": 5,
"dns_record_type": null,
"dns_expected_value": null,
"is_active": true,
"last_checked_at": null,
"last_response_time_ms": null,
"last_error": null,
"last_up_at": null,
"last_down_at": null,
"maintenance_windows": [],
"created_at": "2026-10-26T10:00:00Z",
"updated_at": "2026-10-26T10:00:00Z"
}
}
Example: create a DNS monitor
curl -X POST https://watchcron.com/api/v1/port-monitors \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "DNS A Record", "type": "dns", "host": "example.com", "dns_record_type": "A", "dns_expected_value": "93.184.216.34", "interval_seconds": 600 }'
This creates a DNS monitor that queries the A record for example.com and alerts if the resolved value does not match 93.184.216.34.
Validation errors
If required fields are missing or invalid, the API returns 422:
{
"error": "The port field is required when type is tcp."
}
Get a port monitor
/api/v1/port-monitors/{uuid}
Returns full details for a single port monitor.
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/port-monitors/d4e5f6a7-b8c9-0123-defa-234567890123"
$uuid = 'd4e5f6a7-b8c9-0123-defa-234567890123'; $response = Http::withToken('YOUR_API_KEY') ->get("https://watchcron.com/api/v1/port-monitors/{$uuid}"); $monitor = $response->json('data');
uuid = "d4e5f6a7-b8c9-0123-defa-234567890123" response = requests.get( f"https://watchcron.com/api/v1/port-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) monitor = response.json()["data"]
const uuid = "d4e5f6a7-b8c9-0123-defa-234567890123"; const response = await fetch( `https://watchcron.com/api/v1/port-monitors/${uuid}`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: monitor } = await response.json();
Returns the same port monitor object as shown in Port monitor object. Returns 404 if the UUID does not exist or belongs to a different project.
Update a port monitor
/api/v1/port-monitors/{uuid}
Updates one or more fields on an existing port monitor. Only include the fields you want to change — all fields are optional.
Request body
| Field | Type | Description |
|---|---|---|
name | string | Monitor name (max 255 characters) |
type | string | tcp, udp, dns, or icmp |
host | string | Hostname or IP address (max 255 characters) |
port | integer|null | Port number (1–65535) |
timeout_seconds | integer | Connection timeout (1–60 seconds) |
interval_seconds | integer | Check interval (min 30 seconds) |
dns_record_type | string|null | DNS record type |
dns_expected_value | string|null | Expected DNS value (max 255 characters) |
maintenance_windows | array|null | Maintenance windows (replaces existing) |
curl -X PUT https://watchcron.com/api/v1/port-monitors/d4e5f6a7-b8c9-0123-defa-234567890123 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "SSH Server (Production)", "timeout_seconds": 10, "interval_seconds": 60 }'
$response = Http::withToken('YOUR_API_KEY') ->put("https://watchcron.com/api/v1/port-monitors/{$uuid}", [ 'name' => 'SSH Server (Production)', 'timeout_seconds' => 10, 'interval_seconds' => 60, ]);
response = requests.put( f"https://watchcron.com/api/v1/port-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "name": "SSH Server (Production)", "timeout_seconds": 10, "interval_seconds": 60, }, )
const response = await fetch(`https://watchcron.com/api/v1/port-monitors/${uuid}`, { method: "PUT", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ name: "SSH Server (Production)", timeout_seconds: 10, interval_seconds: 60, }), });
Returns 200 OK with the updated port monitor object.
"maintenance_windows": [...] replaces all existing windows. Send "maintenance_windows": null to clear them.Delete a port monitor
/api/v1/port-monitors/{uuid}
Permanently deletes a port monitor and all its associated check logs.
curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/port-monitors/d4e5f6a7-b8c9-0123-defa-234567890123"
$response = Http::withToken('YOUR_API_KEY') ->delete("https://watchcron.com/api/v1/port-monitors/{$uuid}");
response = requests.delete( f"https://watchcron.com/api/v1/port-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, )
const response = await fetch( `https://watchcron.com/api/v1/port-monitors/${uuid}`, { method: "DELETE", headers: { "Authorization": "Bearer YOUR_API_KEY" }, } );
Returns 204 No Content on success. This action is irreversible.
Pause or unpause a port monitor
/api/v1/port-monitors/{uuid}/pause
Pauses or unpauses a port monitor. While paused, no checks run and no alerts fire.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
paused | boolean | Yes | true to pause, false to unpause |
curl -X PATCH https://watchcron.com/api/v1/port-monitors/d4e5f6a7-b8c9-0123-defa-234567890123/pause \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"paused": true}'
$response = Http::withToken('YOUR_API_KEY') ->patch("https://watchcron.com/api/v1/port-monitors/{$uuid}/pause", [ 'paused' => true, ]);
response = requests.patch( f"https://watchcron.com/api/v1/port-monitors/{uuid}/pause", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={"paused": True}, )
const response = await fetch( `https://watchcron.com/api/v1/port-monitors/${uuid}/pause`, { method: "PATCH", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ paused: true }), } );
Returns 200 OK with the updated port monitor object. The is_active field reflects the new state.
List check logs
/api/v1/port-monitors/{uuid}/logs
Returns a paginated list of check log entries for a specific port monitor, ordered by most recent first.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
per_page | integer | 25 | Results per page |
page | integer | 1 | Page number |
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/port-monitors/d4e5f6a7-b8c9-0123-defa-234567890123/logs?per_page=5"
$response = Http::withToken('YOUR_API_KEY') ->get("https://watchcron.com/api/v1/port-monitors/{$uuid}/logs", [ 'per_page' => 5, ]); $logs = $response->json('data');
response = requests.get( f"https://watchcron.com/api/v1/port-monitors/{uuid}/logs", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"per_page": 5}, ) logs = response.json()["data"]
const response = await fetch( `https://watchcron.com/api/v1/port-monitors/${uuid}/logs?per_page=5`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: logs } = await response.json();
Response 200 OK
{
"data": [
{
"status": "up",
"response_time_ms": 42,
"error": null,
"resolved_value": null,
"checked_at": "2026-10-26T08:15:00Z"
},
{
"status": "down",
"response_time_ms": null,
"error": "Connection timed out",
"resolved_value": null,
"checked_at": "2026-10-26T08:10:00Z"
}
],
"meta": {
"pagination": {
"total": 1440,
"per_page": 5,
"current_page": 1,
"last_page": 288
}
}
}
Log entry fields
| Field | Type | Description |
|---|---|---|
status | string | Result of the check: up or down |
response_time_ms | integer|null | Response time in milliseconds (null if the check failed) |
error | string|null | Error message if the check failed |
resolved_value | string|null | Resolved DNS value (for dns type monitors only) |
checked_at | string | ISO 8601 timestamp of when the check ran |