Get Tunnel
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 ID, and the old one is removed. For persistent state, look at /endpoints/{id} 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/{id}; for health, /endpoints/{id}/health.
Path parameters
id int64 Req
Tunnel ID. Get from /tunnels.
Response (200 OK)
id int64
Tunnel ID.
user_id int64
Provenance — the user who created the tunnel.
name string
Tunnel name.
type string
Tunnel type (e.g.
http, tcp, udp).local_address string
Local target the agent forwards to (
host:port).remote_port int
Assigned remote port (TCP/UDP tunnels).
remote_subdomain string
Assigned remote subdomain (HTTP tunnels).
public_url string
Public URL/address this tunnel is reachable at.
status string
active when at least one agent is connected, otherwise inactive.max_connections int
Connection cap for this tunnel.
created_at, updated_at datetime
Creation and last-update timestamps.
agent_count int
Number of active agents serving this tunnel.
region string
Serving region — where the agent actually connected (stamped at handshake). Transient; empty if the tunnel hasn't reconnected under the current write path.
latest_agent_version string?
Current released agent version, so clients can flag outdated agents. Omitted when unset.
agents object[]
Connected agents (id, name, tags, version, IP, status, weight, connect/last-seen times, etc.).
tags string[]
Durable, dashboard-owned tunnel tags. Always present (empty array when none).
uptime string?
Human-readable uptime since the first active agent connected (e.g.
2d 4h). Populated on the list view.Errors
401 Unauthorized
Missing auth.
404 Not Found
Tunnel doesn't exist (likely already disconnected) or doesn't belong to the calling user's endpoints.
Request
curl "https://api.ngris.com/v1/tunnels/<tunnel_id>" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
t = client.tunnels.get("<tunnel_id>")
print(f"{t['name']} status={t['status']} agents={t['agent_count']}")
Response — 200 OK
{
"id": 4521,
"user_id": 1024,
"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-north-1",
"agents": [
{
"agent_id": "agent-prod-1",
"agent_name": "prod-1",
"agent_version": "1.8.2",
"agent_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"
}