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_2hrGx7r2A3Y4ifgNeG8V7WOvVEA",
				"uri": "https://api.ngrok.com/endpoints/ep_2hrGx7r2A3Y4ifgNeG8V7WOvVEA"
			},
			"forwards_to": "http://localhost:80",
			"id": "tn_2hrGx7r2A3Y4ifgNeG8V7WOvVEA",
			"proto": "https",
			"public_url": "https://cb0b3401d3ba.ngrok.paid",
			"region": "us",
			"started_at": "2024-06-14T06:03:45Z",
			"tunnel_session": {
				"id": "ts_2hrGx1DNcjuVjtOWFtNJ3JQbapo",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2hrGx1DNcjuVjtOWFtNJ3JQbapo"
			}
		},
		{
			"forwards_to": "http://localhost:80",
			"id": "tn_2hrGwrgvKlH0tcJEOHzDPYazFhx",
			"labels": {
				"baz": "qux",
				"foo": "bar"
			},
			"region": "us",
			"started_at": "2024-06-14T06:03:43Z",
			"tunnel_session": {
				"id": "ts_2hrGwksDdG3WFD5pjP7RTkcat0A",
				"uri": "https://api.ngrok.com/tunnel_sessions/ts_2hrGwksDdG3WFD5pjP7RTkcat0A"
			}
		}
	],
	"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_2hrGx7r2A3Y4ifgNeG8V7WOvVEA

Response

Returns a 200 response on success

Example Response

{
	"endpoint": {
		"id": "ep_2hrGx7r2A3Y4ifgNeG8V7WOvVEA",
		"uri": "https://api.ngrok.com/endpoints/ep_2hrGx7r2A3Y4ifgNeG8V7WOvVEA"
	},
	"forwards_to": "http://localhost:80",
	"id": "tn_2hrGx7r2A3Y4ifgNeG8V7WOvVEA",
	"proto": "https",
	"public_url": "https://cb0b3401d3ba.ngrok.paid",
	"region": "us",
	"started_at": "2024-06-14T06:03:45Z",
	"tunnel_session": {
		"id": "ts_2hrGx1DNcjuVjtOWFtNJ3JQbapo",
		"uri": "https://api.ngrok.com/tunnel_sessions/ts_2hrGx1DNcjuVjtOWFtNJ3JQbapo"
	}
}

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