Get Tunnel
GET
/v1/tunnels/{uuid}
Read the state of a single live tunnel — the live wire connection an agent has open to the platform's tunnel-server. Tunnels are ephemeral: every time the agent reconnects (config change, network blip, deploy) it gets a new tunnel (with a new uuid), and the old one is removed. For persistent state, look at /endpoints/{uuid} instead.
Account scope: you can read tunnels belonging to your active account, subject to your role's permissions. Use switch account to inspect a tunnel in a different account.
Use this for live-connection inspection: which agent is connected right now, when did it connect, what's its remote address. For traffic stats, use /stats/tunnels/{uuid}; for health, /endpoints/{uuid}/health.
Path parameters
Deprecated: the legacy integer id is still accepted in the path until the sunset, answered with Deprecation and Sunset headers. Use the uuid.
Response (200 OK)
Provenance — the user who created the tunnel. Omitted when unknown.
Tunnel type (e.g. http, tcp, udp).
Local target the agent forwards to (host:port).
Assigned remote port (TCP/UDP tunnels).
Assigned remote subdomain (HTTP tunnels).
Public URL/address this tunnel is reachable at.
active when at least one agent is connected, otherwise inactive.
Connection cap for this tunnel.
Creation and last-update timestamps.
Number of active agents serving this tunnel.
Serving region — where the agent actually connected (stamped at handshake). Transient; empty if the tunnel hasn't reconnected under the current write path.
Current released agent version, so clients can flag outdated agents. Omitted when unset.
Connected agents (agent_id, name, tags, version, IP, status, weight, connect/last-seen times, etc.). Each carries tunnel_uuid; agents are addressed by their agent_id string.
Durable, dashboard-owned tunnel tags. Always present (empty array when none).
Human-readable uptime since the first active agent connected (e.g. 2d 4h). Populated on the list view.
Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
An integer id after the sunset (integer_id_unsupported).
Tunnel doesn't exist (likely already disconnected) or isn't in your active account — another account's uuid reads exactly like an unknown one.
curl "https://api.ngris.com/v1/tunnels/019ab73a-b951-7031-aea5-1435da834122" \
-H "X-API-KEY: <your_api_key>"
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
t = client.tunnels.get("019ab73a-b951-7031-aea5-1435da834122")
print(f"{t.uuid} {t.name} status={t.status} agents={t.agent_count}")
{
"uuid": "019ab73a-b951-7031-aea5-1435da834122",
"user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
"name": "prod-api",
"type": "http",
"local_address": "127.0.0.1:8080",
"remote_port": 0,
"remote_subdomain": "prod-api",
"public_url": "prod-api.ngris.io",
"status": "active",
"max_connections": 100,
"created_at": "2026-04-20T09:00:00Z",
"updated_at": "2026-04-29T11:00:00Z",
"agent_count": 1,
"region": "eu-fi",
"agents": [
{
"tunnel_uuid": "019ab73a-b951-7031-aea5-1435da834122",
"agent_id": "agent-prod-1",
"agent_name": "prod-1",
"agent_version": "1.8.2",
"ip": "203.0.113.50",
"status": "active",
"connected_at": "2026-04-29T11:00:00Z",
"last_seen_at": "2026-04-29T13:00:05Z"
}
],
"tags": ["prod"],
"latest_agent_version": "1.8.2"
}