List Agents
Lists the agents connected for the account, joined with the tunnel each one serves so you can show the tunnel name, type, and public URL without a second round-trip. Capped at the 50 most recently active agents (ordered by last-seen, newest first) to keep payloads small.
Account scope: returns agents for tunnels belonging to your active account, subject to your role's permissions. Use switch account to inspect a different account.
Response (200 OK)
agents object[]
The agent rows (see fields below). Always present (empty array when none).
active_count int64
Number of returned agents whose
status is active.total_count int64
Number of agents in this response (at most 50).
Agent object
agent_id string
Stable identifier the agent reports at connect time.
agent_version string
Reported agent version. Empty string when unknown.
agent_ip string
Source IP the agent connected from. Empty string when unknown.
status string
Connection status (e.g.
active, disconnected).connected_at datetime
When this agent connection was established (RFC 3339).
last_seen_at datetime
Last time the tunnel-server heard from this agent (RFC 3339). The list is sorted by this field, descending.
disconnected_at datetime?
When the agent disconnected. Omitted while still connected.
tunnel_id int64
The tunnel this agent serves. See GET /v1/tunnels/{id}.
tunnel_name string
Name of the served tunnel. Empty string when unset.
tunnel_type string
Type of the served tunnel (e.g.
http, tcp, udp). Empty string when unset.tunnel_url string
Public URL/address of the served tunnel. Empty string when unset.
Errors
401 Unauthorized
Missing auth.
403 Forbidden
Your role lacks read permission on the traffic-inspector resource for the active account.
Request
curl -X GET "https://api.ngris.com/v1/agents" \
-H "X-API-KEY: <your_api_key>"
Response — 200 OK
{
"agents": [
{
"agent_id": "agent-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",
"tunnel_id": 4521,
"tunnel_name": "prod-api",
"tunnel_type": "http",
"tunnel_url": "prod-api.ngris.io"
}
],
"active_count": 1,
"total_count": 1
}