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_2na2JAD0UFlf8ok8xugXdiq85bj",
				"uri": "https://api.ngrok.com/endpoints/ep_2na2JAD0UFlf8ok8xugXdiq85bj"
			},
			"forwards_to": "http://localhost:80",
			"id": "tn_2na2JAD0UFlf8ok8xugXdiq85bj",
			"proto": "https",
			"public_url": "https://12e848c1f74e.ngrok.paid",
			"region": "us",
			"started_at": "2024-10-17T20:26:31Z",
			"tunnel_session": {
				"id": "ts_2na2JAw7W7P25FYH2EvvkLSyesJ",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2na2JAw7W7P25FYH2EvvkLSyesJ"
			}
		},
		{
			"forwards_to": "http://localhost:80",
			"id": "tn_2na2IcFurydSHExOgvv7vKB3vOc",
			"labels": {
				"baz": "qux",
				"foo": "bar"
			},
			"region": "us",
			"started_at": "2024-10-17T20:26:27Z",
			"tunnel_session": {
				"id": "ts_2na2IeLxkx9rHVDmPSWWgFAy9wd",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2na2IeLxkx9rHVDmPSWWgFAy9wd"
			}
		}
	],
	"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_2na2JAD0UFlf8ok8xugXdiq85bj

Response

Returns a 200 response on success

Example Response

{
	"endpoint": {
		"id": "ep_2na2JAD0UFlf8ok8xugXdiq85bj",
		"uri": "https://api.ngrok.com/endpoints/ep_2na2JAD0UFlf8ok8xugXdiq85bj"
	},
	"forwards_to": "http://localhost:80",
	"id": "tn_2na2JAD0UFlf8ok8xugXdiq85bj",
	"proto": "https",
	"public_url": "https://12e848c1f74e.ngrok.paid",
	"region": "us",
	"started_at": "2024-10-17T20:26:31Z",
	"tunnel_session": {
		"id": "ts_2na2JAw7W7P25FYH2EvvkLSyesJ",
		"uri": "https://api.ngrok.com/tunnel_sessions/ts_2na2JAw7W7P25FYH2EvvkLSyesJ"
	}
}

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