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

Inspect one forwarding service with its events, logs and diagnosed cause

Returns the service row, its last error, recent VPS events, box and VPS log lines and a diagnosed cause and hint. Reads logs over SSH, so it can take some seconds.

  • Read only
  • Basic auth
  • Panel API · since v21.2.34
  • Hub: routine call
  • getVpsForwardingServiceDetail
GET/v2/forwarding/service_detail

Query parameters

namestringrequired

Service name from /v2/forwarding/get_mapping_ports.

Example xlocal@4001

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

Service detail, or a refusal.

statusbooleanoptional
msgstringoptional
dataobjectoptional
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.last_errorobject | nulloptional
data.vps_statestringoptional
data.eventsobject[]optional
data.events[].timenumber | nulloptional
data.events[].msgstringoptional
data.events[].wherestringoptional
data.logsobjectoptional
data.logs.boxstring[]optional
data.logs.vpsstring[]optional
data.causestring | nulloptional
data.hintstring | nulloptional

Errors returned in msg

msgMeaningWhat to do
Service NAME not foundNo service has this name.Take the name from /v2/forwarding/get_mapping_ports.
Failed to inspect NAME: ...Reading the logs failed (for example the VPS is unreachable).Check /v2/forwarding/vps_health.
Verified against XProxy v21.3.2 on Nov 17, 2026