List monitors

GET

/servers

const url = 'https://app.tunnelhq.com/api/v1/servers?family=tunnel&active_only=1&status=healthy&protocol=wireguard&limit=500&offset=0';
const options = {method: 'GET', headers: {'X-Project-Id': 'prj_12', 'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://app.tunnelhq.com/api/v1/servers?family=tunnel&active_only=1&status=healthy&protocol=wireguard&limit=500&offset=0' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Project-Id: prj_12'

Lists the project’s monitors, sorted by name: VPN monitors (tunnels) by default, or Uptime checks with family. Any role in the project can call it. List rows never include a heartbeat’s heartbeat_url.

total counts the monitors that match the filters, before limit and offset apply.

Need an API key? See Getting an API key.

Authorizations

ApiKeyHeader
BearerAuth

Parameters

Header Parameters

X-Project-Id

required

string

The project, as prj_12 or 12. A workspace key can only reach its own workspace’s projects.

Example

prj_12

Query Parameters

family

string

default: tunnel

Allowed values: tunnel uptime all

Which monitors: tunnel (the default), uptime, or all. Anything else is refused with 400 “family must be tunnel, uptime or all”.

active_only

string

Allowed values: 1 true

1 or true lists only monitors that aren’t paused.

status

healthy: the latest check passed. With several locations, at least one is up and none is down.
down: confirmed down. With several locations, at least one is down and none is up.
partial: several locations, some up and some down.
degraded: the latest check has no verdict yet (retrying, inconclusive, or a fault on TunnelHQ’s checker), or the server refused the monitor’s credentials. The dashboard shows the first case as Unknown and the second as Degraded.
paused: the monitor is paused.
unknown: the monitor hasn’t been checked yet. The dashboard shows it as Pending.

string

Allowed values: healthy down partial degraded paused unknown

Only monitors with this status. Left out or empty, no filter. Any other word is refused with 400 “status must be healthy, down, degraded, partial, paused or unknown.”

protocol

string

Allowed values: wireguard amneziawg openvpn openconnect ikev2 vless vmess trojan shadowsocks hysteria2 tuic

Only monitors of this protocol.

search

string

Only monitors whose name contains this text, ignoring case.

limit

integer

default: 500 >= 1 <= 500

How many monitors to return.

offset

integer

How many matching monitors to skip.

Responses

200

The monitors.

application/json

object

servers

required

Array<object>

object

required

string

name

required

string

type

required

vpn for a tunnel, or the Uptime check’s type (push is a heartbeat).

string

Allowed values: vpn http keyword ping port dns push

protocol

required

One of:

string
string

string

Allowed values: wireguard amneziawg openvpn openconnect ikev2 vless vmess trojan shadowsocks hysteria2 tuic

status

required

healthy: the latest check passed. With several locations, at least one is up and none is down.
down: confirmed down. With several locations, at least one is down and none is up.
partial: several locations, some up and some down.
degraded: the latest check has no verdict yet (retrying, inconclusive, or a fault on TunnelHQ’s checker), or the server refused the monitor’s credentials. The dashboard shows the first case as Unknown and the second as Degraded.
paused: the monitor is paused.
unknown: the monitor hasn’t been checked yet. The dashboard shows it as Pending.

string

Allowed values: healthy down partial degraded paused unknown

aggregate_status

required

Always the same as status.

string

Allowed values: healthy down partial degraded paused unknown

active

required

false when the monitor is paused.

boolean

interval

required

Seconds between scheduled checks.

integer | null

latency_ms

required

The latest check’s time, in milliseconds. For a tunnel, one round trip through the tunnel. For an Uptime check: the response time (website and keyword), the average round trip (ping), the TCP connect time (TCP port), the query time (DNS, null unless the server answered every question), or the ping value the job sent (heartbeat). Null when that check failed or measured none.

integer | null

connect_ms

Tunnels only: check rows don’t have it. How long the tunnel took to come up in its latest check, in milliseconds. Null when that check failed or measured none. For VLESS, VMess, Trojan, Shadowsocks, Hysteria2, and TUIC, it’s the time to first contact with the server.

integer | null

region

required

Where the latest check ran from, as any or a lowercase country code. null before the first check.

string | null

locations

required

The locations the monitor tests from. ["any"] unless specific locations were chosen.

Array<string>

disabled_locations

required

Locations that are paused. Never includes any.

Array<string>

regional_status

required

The latest result per location, keyed by location code. {} before the first check.

object

key

additional properties

object

status

required

pending means no verdict yet; degraded, that the server refused the credentials; unavailable, that no checker is available there, so the location is left out of the status.

string

Allowed values: up down pending degraded unavailable unknown

last_check

required

When that location last checked, in ISO 8601 UTC. Empty if unknown.

string

ping_ms

required

number | null

error_category

Why the check failed, when it did.

string

proxy_used

Present only when the check ran through a relay.

boolean

notify_on_partial

required

Whether a partial outage alerts.

boolean

tags

required

Tag names.

Array<string>

last_checked

required

When the latest check ran, in UTC, as YYYY-MM-DD HH:MM:SS with no time zone marker.

string | null

subscription

Present only on monitors imported from a subscription URL. One monitor stands for every config in the URL that points at the same server.

object

subscription_url_id

string | null

server_address

string | null

server_name

string | null

config_count

integer

healthy_count

integer

configs

The latest result for each config.

Array<object>

object

tag

The config’s name in the subscription.

string

type

The config’s protocol, such as vless.

string

server

string

port

integer | string

success

boolean

total_ms

number

error

string

error_category

string

public_ip

The address traffic left from, when the check passed.

string

engine_used

string

region_results

The same fields per location.

object

url

Uptime checks only: the address a website or keyword check requests.

string | null

host

Uptime checks only: the host a ping or TCP port check reaches, or the DNS server a DNS check asks.

string | null

domain

Uptime checks only: the domain a DNS check asks about. null for other checks.

string | null

port

Uptime checks only: the TCP port check’s port, or 53 for DNS.

integer | null

keyword

Uptime checks only: the text a keyword check looks for, or the text a DNS answer must contain.

string | null

invert_keyword

Uptime checks only: true when a keyword check alerts on finding the keyword.

boolean

accepted_statuscodes

Uptime checks only: status codes that count as up, such as 200-299.

Array<string>

certificate

Uptime checks only: the certificate the latest check saw, or null before one was seen.

object

valid

boolean

days_remaining

integer

ssl_expiration

Uptime checks only: days before the certificate expires to alert. null is off.

integer | null

domain_expiration

Uptime checks only: days before the domain expires to alert. null is off.

integer | null

ip_version

Uptime checks only: ipv4 or ipv6, or null for both.

string | null

Allowed values: ipv4 ipv6

period

Heartbeats only: the longest time between two calls from the job, in seconds. interval shows the same value.

integer

grace

Heartbeats only: how late a call can be before the heartbeat is down, in seconds.

integer

heartbeat_url

Heartbeats only, and only from Create, Get, and Update monitor, to callers who can edit monitors: the address the job calls. Treat it as a secret.

string

total

required

Monitors matching the filters.

integer

Example

{
  "servers": [
    {
      "id": "srv_42",
      "name": "fra-wg-01",
      "type": "vpn",
      "protocol": "wireguard",
      "status": "healthy",
      "aggregate_status": "healthy",
      "active": true,
      "interval": 180,
      "latency_ms": 157,
      "connect_ms": 364,
      "region": "any",
      "locations": [
        "any"
      ],
      "disabled_locations": [],
      "regional_status": {
        "any": {
          "status": "up",
          "last_check": "2026-09-25T14:30:02.000Z",
          "ping_ms": 212
        }
      },
      "notify_on_partial": false,
      "tags": [
        "production"
      ],
      "last_checked": "2026-09-25 14:30:02"
    }
  ],
  "total": 1
}

Headers

X-RateLimit-Limit

integer

Requests the workspace’s plan allows per minute.

X-RateLimit-Remaining

integer

Requests left in the current minute.

X-RateLimit-Reset

integer

Unix time, in seconds, when the current minute ends.

400

The status or family filter isn’t one of its words, or the X-Project-Id header is missing or malformed.

application/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": true,
  "code": 400,
  "message": "status must be healthy, down, degraded, partial, paused or unknown."
}

{
  "error": true,
  "code": 400,
  "message": "family must be tunnel, uptime or all"
}

{
  "error": true,
  "code": 400,
  "message": "X-Project-Id header is required (e.g. prj_1 or numeric id)"
}

401

The API key is missing, wrong, expired, switched off, or no longer valid.

application/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": true,
  "code": 401,
  "message": "API key is required. Provide X-API-Key header or Authorization: Bearer <key>"
}

{
  "error": true,
  "code": 401,
  "message": "Invalid or expired API key"
}

{
  "error": true,
  "code": 401,
  "message": "API key has expired"
}

{
  "error": true,
  "code": 401,
  "message": "API key owner account is inactive"
}

{
  "error": true,
  "code": 401,
  "message": "This API key's workspace access has been removed"
}

403

The key can’t reach this project.

application/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Examples

{
  "error": true,
  "code": 403,
  "message": "This API key is scoped to a different organization"
}

{
  "error": true,
  "code": 403,
  "message": "You do not have access to this project"
}

404

No active project has this ID.

application/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Example

{
  "error": true,
  "code": 404,
  "message": "Project not found or inactive"
}

429

A usage limit was reached, or this IP address made too many requests with a wrong key.

Usage limits are per workspace and plan: per minute (Retry-After: 60), per day (Retry-After: 3600), and per month (no Retry-After). They use their own body shape. An IP address may send 10 wrong keys a minute; one more is allowed every 6 seconds. While that allowance is used up, every request from the address is refused, even one with a valid key.

application/json

One of:

object
object

object

error

required

string

Allowed values: Rate limit exceeded Daily limit exceeded Monthly limit exceeded

message

required

string

retry_after

Seconds to wait. Absent for the monthly limit.

integer

Examples

{
  "error": "Rate limit exceeded",
  "message": "Per-minute limit of 60 requests exceeded",
  "retry_after": 60
}

{
  "error": "Daily limit exceeded",
  "message": "Daily limit of 25000 requests exceeded",
  "retry_after": 3600
}

{
  "error": "Monthly limit exceeded",
  "message": "Monthly limit of 250000 requests exceeded"
}

{
  "error": true,
  "code": 429,
  "message": "Too many failed API key attempts from this address. Wait a few seconds and try again.",
  "retry_after": 6
}

Headers

Retry-After

integer

Seconds to wait. 60 for the per-minute limit, 3600 for the daily limit, 6 after wrong keys. Absent for the monthly limit.

500

Something failed on TunnelHQ’s side.

application/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Example

{
  "error": true,
  "code": 500,
  "message": "Internal server error"
}