API Reference
Dashboard
  1. API Reference
  2. Box API
  3. VPS forwarding

List every forwarded port with its VPS port and state

Returns one row per forwarding service (relay tunnels and per-port forwards) with the local port, public VPS port, status and the last error with its diagnosed cause.

  • Read only
  • Basic auth
  • Panel API · since v20.8.0
  • Hub: routine call
  • getVpsForwardingMappingPorts
GET/v2/forwarding/get_mapping_ports

Authentication

Needs a trusted caller (loopback, LAN unless "force auth for local" is on, whitelisted IP, allowed Tailscale) or valid dashboard Basic credentials, which are checked only when dashboard authentication is enabled.

Responses

Rows, or the error text.

statusbooleanoptional
msgstringoptional
dataobject[]optional
data[].service_namestringoptional

Unit name, e.g. xlocal@4001 or xwg@20000.

data[].svc_typestringoptional
data[].modem_positioninteger | nulloptional
data[].vps_addressstring | nulloptional
data[].relay_portinteger | nulloptional
data[].local_portinteger | nulloptional
data[].vps_portinteger | nulloptional
data[].statusstring | nulloptional

e.g. running, starting, relay_down.

data[].service_liveboolean | string | nulloptional
data[].memory_usenumber | string | nulloptional
data[].last_checknumber | nulloptional
data[].enginestringoptional
data[].networkstringoptional
data[].connsinteger | nulloptional
data[].up_mbpsnumber | nulloptional
data[].down_mbpsnumber | nulloptional
data[].errorstring | nulloptional
data[].causestring | nulloptional

Errors returned in msg

msgMeaningWhat to do
Failed to get mapping ports: ...Reading the service table failed.Retry; check the controller log.
Verified against XProxy v21.3.2 on Nov 17, 2026