Tunnels

List Tunnels

List all online tunnels currently running on the account.

Request

GET /tunnels

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tunnels

Response

Returns a 200 response on success

Example Response

{
	"next_page_uri": null,
	"tunnels": [
		{
			"endpoint": {
				"id": "ep_2gsqKJc7E2Yun6eMH9USo2Fwvub",
				"uri": "https://api.ngrok.com/endpoints/ep_2gsqKJc7E2Yun6eMH9USo2Fwvub"
			},
			"forwards_to": "http://localhost:80",
			"id": "tn_2gsqKJc7E2Yun6eMH9USo2Fwvub",
			"proto": "https",
			"public_url": "https://0cdfbb854910.ngrok.paid",
			"region": "us",
			"started_at": "2024-05-23T20:36:07Z",
			"tunnel_session": {
				"id": "ts_2gsqKNiuJimrHieovlocpQSghqS",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2gsqKNiuJimrHieovlocpQSghqS"
			}
		},
		{
			"forwards_to": "http://localhost:80",
			"id": "tn_2gsqJzggkWWpJbLh3s3Ed5od7SM",
			"labels": {
				"baz": "qux",
				"foo": "bar"
			},
			"region": "us",
			"started_at": "2024-05-23T20:36:04Z",
			"tunnel_session": {
				"id": "ts_2gsqK0QEUTLNJYbXsYVDqsQWwmt",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2gsqK0QEUTLNJYbXsYVDqsQWwmt"
			}
		}
	],
	"uri": "https://api.ngrok.com/tunnels"
}

Fields

Name	Type	Description
tunnels	Tunnel	the list of all online tunnels on this account
uri	string	URI of the tunnels list API resource
next_page_uri	string	URI of the next page, or null if there is no next page

Tunnel fields

Name	Type	Description
id	string	unique tunnel resource identifier
public_url	string	URL of the ephemeral tunnel's public endpoint
started_at	string	timestamp when the tunnel was initiated in RFC 3339 format
metadata	string	user-supplied metadata for the tunnel defined in the ngrok configuration file. See the tunnel metadata configuration option In API version 0, this value was instead pulled from the top-level metadata configuration option.
proto	string	tunnel protocol for ephemeral tunnels. one of http, https, tcp or tls
region	string	identifier of tune region where the tunnel is running
tunnel_session	Ref	reference object pointing to the tunnel session on which this tunnel was started
endpoint	Ref	the ephemeral endpoint this tunnel is associated with, if this is an agent-initiated tunnel
labels	Map<string, string>	the labels the tunnel group backends will match against, if this is a backend tunnel
backends	Ref	tunnel group backends served by this backend tunnel
forwards_to	string	upstream address the ngrok agent forwards traffic over this tunnel to. this may be expressed as a URL or a network address.

Ref fields

Name	Type	Description
id	string	a resource identifier
uri	string	a uri for locating a resource

Get Tunnel

Get the status of a tunnel by ID

Request

GET /tunnels/{id}

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tunnels/tn_2gsqKJc7E2Yun6eMH9USo2Fwvub

Response

Returns a 200 response on success

Example Response

{
	"endpoint": {
		"id": "ep_2gsqKJc7E2Yun6eMH9USo2Fwvub",
		"uri": "https://api.ngrok.com/endpoints/ep_2gsqKJc7E2Yun6eMH9USo2Fwvub"
	},
	"forwards_to": "http://localhost:80",
	"id": "tn_2gsqKJc7E2Yun6eMH9USo2Fwvub",
	"proto": "https",
	"public_url": "https://0cdfbb854910.ngrok.paid",
	"region": "us",
	"started_at": "2024-05-23T20:36:07Z",
	"tunnel_session": {
		"id": "ts_2gsqKNiuJimrHieovlocpQSghqS",
		"uri": "https://api.ngrok.com/tunnel_sessions/ts_2gsqKNiuJimrHieovlocpQSghqS"
	}
}

Fields

Name	Type	Description
id	string	unique tunnel resource identifier
public_url	string	URL of the ephemeral tunnel's public endpoint
started_at	string	timestamp when the tunnel was initiated in RFC 3339 format
metadata	string	user-supplied metadata for the tunnel defined in the ngrok configuration file. See the tunnel metadata configuration option In API version 0, this value was instead pulled from the top-level metadata configuration option.
proto	string	tunnel protocol for ephemeral tunnels. one of http, https, tcp or tls
region	string	identifier of tune region where the tunnel is running
tunnel_session	Ref	reference object pointing to the tunnel session on which this tunnel was started
endpoint	Ref	the ephemeral endpoint this tunnel is associated with, if this is an agent-initiated tunnel
labels	Map<string, string>	the labels the tunnel group backends will match against, if this is a backend tunnel
backends	Ref	tunnel group backends served by this backend tunnel
forwards_to	string	upstream address the ngrok agent forwards traffic over this tunnel to. this may be expressed as a URL or a network address.

Ref fields

Name	Type	Description
id	string	a resource identifier
uri	string	a uri for locating a resource