List Tunnels
Retrieve a list of all active tunnels.
Account scope: this returns the tunnels of your active account, shared with all its members per your role's permissions. Use switch account to act in a different account.
Response shape: the response is a paginated wrapper — { "items": [...], "total", "page", "page_size", "latest_agent_version" } — not a bare array. Each entry in items is a full Tunnel object (same fields as GET /v1/tunnels/{uuid}). Address a tunnel by its uuid.
Query parameters
page int
1-based page number. Default
1.page_size int
Items per page. Default
15; values above 200 are capped at 200.q string
Free-text filter over name, local address, public URL, type, status, and subdomain.
Response (200 OK)
items object[]
The tunnels on this page, each a full Tunnel object (see GET /v1/tunnels/{uuid}). Always present;
[] when there are none.total int
Number of matching tunnels across all pages.
page int
The page that was returned.
page_size int
The effective page size.
latest_agent_version string
The current agent release, to compare with each agent's
agent_version. Empty string when not published.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.
Request
curl -X GET "https://api.ngris.com/v1/tunnels" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
page = client.tunnels.list()
for t in page["items"]:
print(t["uuid"], t["public_url"])
Response
{
"items": [
{
"uuid": "019ab73a-b951-7031-aea5-1435da834122",
"user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
"name": "app-1",
"type": "http",
"local_address": "127.0.0.1:8080",
"remote_port": 0,
"remote_subdomain": "app-1",
"public_url": "app-1.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",
"uptime": "2d 4h",
"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",
"last_seen_at": "2026-04-29T13:00:05Z"
}
],
"tags": ["prod"]
}
],
"total": 1,
"page": 1,
"page_size": 15,
"latest_agent_version": "1.8.2"
}
Was this helpful?