List monitors

GET

/servers

const url = 'https://app.tunnelhq.com/api/v1/servers?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?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 VPN monitors, sorted by name. Any role in the project can call it.

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

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.

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

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

Latency of the latest check, in milliseconds.

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

total

required

Monitors matching the filters.

integer

Example

{
  "servers": [
    {
      "id": "srv_42",
      "name": "fra-wg-01",
      "protocol": "wireguard",
      "status": "healthy",
      "aggregate_status": "healthy",
      "active": true,
      "interval": 180,
      "latency_ms": 212,
      "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 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": "X-Project-Id header is required (e.g. prj_1 or numeric id)"
}

{
  "error": true,
  "code": 400,
  "message": "Invalid project ID format (use 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"
}