−50%

50% off your first month on any paid plan · code WELCOME50 · until Nov 30

Start free →

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

GET /api/v1/port-monitors

Returns a paginated list of all port monitors in the project associated with your API key.

Query parameters

ParameterTypeDefaultDescription
statusstring—Filter by status (up, down, paused)
typestring—Filter by monitor type (tcp, udp, dns, icmp)
per_pageinteger25Results per page
pageinteger1Page 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

JSON
{
  "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:

FieldTypeDescription
uuidstringUnique identifier (UUID v4). Used in all API URLs.
namestringDisplay name of the monitor
typestringMonitor type: tcp, udp, dns, or icmp
hoststringHostname or IP address to check
portinteger|nullPort number (used for tcp and udp types)
statusstringCurrent status: up, down, or paused
interval_secondsintegerCheck interval in seconds (default: 300)
timeout_secondsintegerConnection timeout in seconds (default: 5)
dns_record_typestring|nullDNS record type to query (for dns type only)
dns_expected_valuestring|nullExpected DNS record value (for dns type only)
is_activebooleanWhether monitoring is active (not paused)
last_checked_atstring|nullISO 8601 timestamp of last check
last_response_time_msinteger|nullResponse time of last check in milliseconds
last_errorstring|nullError message from last failed check
last_up_atstring|nullISO 8601 timestamp of last successful check
last_down_atstring|nullISO 8601 timestamp of last failed check
maintenance_windowsarrayConfigured maintenance windows (alerts suppressed during these periods)
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Type values

TypeDescription
tcpTCP port check — verifies a TCP connection can be established on the specified port
udpUDP connectivity check — sends a UDP packet to the specified port and checks for a response
dnsDNS record check — queries a DNS record and optionally validates the resolved value
icmpICMP ping — sends an ICMP echo request to verify the host is reachable

Create a port monitor

POST /api/v1/port-monitors

Request body

FieldTypeRequiredDescription
namestringYesMonitor name (max 255 characters)
typestringYestcp, udp, dns, or icmp
hoststringYesHostname or IP address (max 255 characters)
portintegerIf tcp/udpPort number (1–65535). Required for tcp and udp types.
timeout_secondsintegerNoConnection timeout in seconds (1–60, default: 5)
interval_secondsintegerNoCheck interval in seconds (min 30, default: 300)
dns_record_typestringNoDNS record type: A, AAAA, MX, CNAME, TXT, etc. (for dns type)
dns_expected_valuestringNoExpected DNS value to match (max 255 characters, for dns type)
maintenance_windowsarrayNoMaintenance windows during which alerts are suppressed
Port requirement: The 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

JSON
{
  "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

POST /api/v1/port-monitors
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:

422 response
{
  "error": "The port field is required when type is tcp."
}

Get a port monitor

GET /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

PUT /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

FieldTypeDescription
namestringMonitor name (max 255 characters)
typestringtcp, udp, dns, or icmp
hoststringHostname or IP address (max 255 characters)
portinteger|nullPort number (1–65535)
timeout_secondsintegerConnection timeout (1–60 seconds)
interval_secondsintegerCheck interval (min 30 seconds)
dns_record_typestring|nullDNS record type
dns_expected_valuestring|nullExpected DNS value (max 255 characters)
maintenance_windowsarray|nullMaintenance 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.

Note on maintenance windows: Sending "maintenance_windows": [...] replaces all existing windows. Send "maintenance_windows": null to clear them.

Delete a port monitor

DELETE /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

PATCH /api/v1/port-monitors/{uuid}/pause

Pauses or unpauses a port monitor. While paused, no checks run and no alerts fire.

Request body

FieldTypeRequiredDescription
pausedbooleanYestrue 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

GET /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

ParameterTypeDefaultDescription
per_pageinteger25Results per page
pageinteger1Page 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

JSON
{
  "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

FieldTypeDescription
statusstringResult of the check: up or down
response_time_msinteger|nullResponse time in milliseconds (null if the check failed)
errorstring|nullError message if the check failed
resolved_valuestring|nullResolved DNS value (for dns type monitors only)
checked_atstringISO 8601 timestamp of when the check ran
Pricing Docs
Log in Start free →