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/{id}).
Query parameters
page int
1-based page number. Default
1.page_size int
Items per page (capped by the server max).
q string
Free-text filter over name, local address, public URL, type, status, and subdomain.
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.id, t.public_url)
Response
{
"items": [
{
"id": 10,
"user_id": 1024,
"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-north-1",
"uptime": "2d 4h",
"agents": [
{
"agent_id": "agent-prod-1",
"agent_name": "prod-1",
"agent_version": "1.8.2",
"agent_ip": "203.0.113.50",
"last_seen_at": "2026-04-29T13:00:05Z"
}
],
"tags": ["prod"]
}
],
"total": 1,
"page": 1,
"page_size": 25,
"latest_agent_version": "1.8.2"
}