TCP port check

What it verifies

A TCP port monitor connects to host and port at its interval from each of its regions, once per resolved address. It judges only whether the connection was accepted, refused, or timed out, and it records how long the connect took. It sends no payload and reads no banner.

Use it when

• A service listens on a port but has no HTTP endpoint, for example a database, a message queue, or an SSH, LDAP, or Redis port.
• Reachability of the port is the question, not the protocol behind it.
• A TLS port without HTTP should have its certificate watched without a second monitor.

It does not speak the protocol behind the port: no banner, no login, and no query. For a mail server, use the SMTP or IMAP check, and for an HTTP endpoint, use the HTTP(S) check. For a port that upgrades to TLS only after a plain dialog (STARTTLS), use the SMTP or IMAP check to watch its certificate.

Swipe sideways to inspect the product view.

app.perstat.io

Configuration

Target. A host name or IP address without scheme, path, or spaces (labels up to 63 characters, 253 in total), plus a port from 1 to 65535. The probe resolves the host through its own resolver at check time.

TLS certificate

With the switch on, a passing connect is followed by one direct TLS handshake per check, not per address, on the monitor’s port unless tls_cert.port names another one. The probe judges the certificate against your expiry, issuer, and subject rules. Without the switch, the check reads no certificate at all, and the monitor view shows none.

How a check runs

1. The probe reads the configuration. A missing port ends the check as an error before any network access.
2. When a check is due, each region resolves the host through the node’s own resolver. It validates every address of the selected family against the blocked ranges.
3. Every address gets one TCP connect with a 10 s timeout. The time to the accepted connection is the response time of that address.
4. Only a passing check with the TLS certificate sub-check on runs the certificate policy. It runs once per check, as a direct TLS handshake on the monitor’s port or on tls_cert.port.
5. The region sends its result to the control plane. Once the alert policy’s quorum of regions and consecutive checks agrees, an incident opens.

Swipe sideways to inspect the product view.

app.perstat.io

What a result contains

Connection time

Time from the connect call to the accepted connection, per region and per address (latency_ms).

Detail line

One line that says what happened: the port is open, the connection was refused with the reason, or the connect timed out.

Certificate

With the sub-check on: common name and alternative names, issuer, validity dates, and self-signed and trust status. Once the warning window is reached, the result also carries the expiry advisory.

Region, family, address

Every result carries the region that measured it, and one sub-result per IP family and per address.

States and severity

• okThe connection was accepted on every checked address. A certificate inside its warning window keeps this state.
• degradedOne IP family, or one of several resolved addresses, fails while the others answer, at the default family_fail_severity. A single connect has no degraded outcome.
• downThe connection is refused or times out, or the host does not resolve or resolves to a blocked address. With the sub-check on, a failing certificate policy counts too: expired, rejected handshake, or issuer or subject mismatch. With family_fail_severity: failed, one failing family counts here as well.
• errorThe configuration cannot run because the port is missing. It counts as an outage with severity critical.

Confirmed by quorum: by default, 2 regions must report the failure before an incident opens. The organization default asks for 2 regions and 2 consecutive checks. A monitor can carry its own rule with count or percent, consecutive checks, and a minimum duration.

Plans and limits

Shortest interval

300 s on Free, 60 s on Pulse, 30 s on Sentinel, 15 s on Command, and 10 s on Enterprise. The web form offers 30 s, 1 min, 5 min, 15 min, and 1 h. The 15 s and 10 s floors are reachable only through MCP.

Regions

2 of 6 on Free, 3 of 6 on Pulse, and all 6 from Sentinel. More regions than the plan allows are rejected, not trimmed.

Monitors

10 on Free, 50 on Pulse, 150 on Sentinel, 500 on Command, and a custom quota on Enterprise. Eleven probe types share this quota, while host agents and heartbeats have their own.

Compare every plan limit

From the pipeline or an agent

The same config works in the deploy step, in an MCP client such as Claude Code, and in the form above. create_monitor needs an organization-wide API key. If you omit regions, the plan picks its default.

{
  "name": "Postgres primary",
  "type": "tcp",
  "interval_seconds": 60,
  "config": {
    "host": "db.example.com",
    "port": 5432
  }
}

Every interface, with its boundary

Limits

• The check reads no banner, runs no protocol dialog, and sends no payload. It ends when the connection is accepted.
• Port 0 is rejected. A monitor saved without a port ends every check as an error.
• The TLS sub-check is a direct handshake on the monitor’s port unless tls_cert.port names another one. For a port that upgrades to TLS after a plain dialog (STARTTLS), use the SMTP or IMAP check.
• The probe does not connect to targets that resolve to loopback, private, link-local, cloud metadata, or similar addresses. The check fails with the detail internal or private, blocked. Saving such a monitor is not prevented.
• Not every region probes IPv6, so selecting ipv6 restricts the usable regions.

Related check types

• HTTP(S) checkAvailability and response of a URL, with assertions on status, body, and TLS.
• TLS certificate checkExpiry, issuer, and subject of a certificate by direct TLS handshake, with an advisory ahead of expiry.
• SMTP checkBanner and EHLO of a mail server, with an optional certificate check over STARTTLS or implicit TLS.
• Ping checkReachability of a host over ICMP echo: replies, loss, and average round trip from every region.

All check types