Skip to main content

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_2k5oiZcp6XXygzSQptY1MaO5DRs",
"uri": "https://api.ngrok.com/endpoints/ep_2k5oiZcp6XXygzSQptY1MaO5DRs"
},
"forwards_to": "http://localhost:80",
"id": "tn_2k5oiZcp6XXygzSQptY1MaO5DRs",
"proto": "https",
"public_url": "https://edb30816df90.ngrok.paid",
"region": "us",
"started_at": "2024-08-02T07:15:26Z",
"tunnel_session": {
"id": "ts_2k5oigJTuEAsyRrYeVB0qfwz0nz",
"uri": "https://api.ngrok.com/tunnel_sessions/ts_2k5oigJTuEAsyRrYeVB0qfwz0nz"
}
},
{
"forwards_to": "http://localhost:80",
"id": "tn_2k5oiRFOzBIVpy6YJd6gXaVQu8r",
"labels": {
"baz": "qux",
"foo": "bar"
},
"region": "us",
"started_at": "2024-08-02T07:15:24Z",
"tunnel_session": {
"id": "ts_2k5oiRI4z6fu8lh6FrDcrOEs1pF",
"uri": "https://api.ngrok.com/tunnel_sessions/ts_2k5oiRI4z6fu8lh6FrDcrOEs1pF"
}
}
],
"uri": "https://api.ngrok.com/tunnels"
}

Fields

NameTypeDescription
tunnelsTunnelthe list of all online tunnels on this account
uristringURI of the tunnels list API resource
next_page_uristringURI of the next page, or null if there is no next page

Tunnel fields

NameTypeDescription
idstringunique tunnel resource identifier
public_urlstringURL of the ephemeral tunnel's public endpoint
started_atstringtimestamp when the tunnel was initiated in RFC 3339 format
metadatastringuser-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.
protostringtunnel protocol for ephemeral tunnels. one of http, https, tcp or tls
regionstringidentifier of tune region where the tunnel is running
tunnel_sessionRefreference object pointing to the tunnel session on which this tunnel was started
endpointRefthe ephemeral endpoint this tunnel is associated with, if this is an agent-initiated tunnel
labelsMap<string, string>the labels the tunnel group backends will match against, if this is a backend tunnel
backendsReftunnel group backends served by this backend tunnel
forwards_tostringupstream address the ngrok agent forwards traffic over this tunnel to. this may be expressed as a URL or a network address.

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa 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_2k5oiZcp6XXygzSQptY1MaO5DRs

Response

Returns a 200 response on success

Example Response

{
"endpoint": {
"id": "ep_2k5oiZcp6XXygzSQptY1MaO5DRs",
"uri": "https://api.ngrok.com/endpoints/ep_2k5oiZcp6XXygzSQptY1MaO5DRs"
},
"forwards_to": "http://localhost:80",
"id": "tn_2k5oiZcp6XXygzSQptY1MaO5DRs",
"proto": "https",
"public_url": "https://edb30816df90.ngrok.paid",
"region": "us",
"started_at": "2024-08-02T07:15:26Z",
"tunnel_session": {
"id": "ts_2k5oigJTuEAsyRrYeVB0qfwz0nz",
"uri": "https://api.ngrok.com/tunnel_sessions/ts_2k5oigJTuEAsyRrYeVB0qfwz0nz"
}
}

Fields

NameTypeDescription
idstringunique tunnel resource identifier
public_urlstringURL of the ephemeral tunnel's public endpoint
started_atstringtimestamp when the tunnel was initiated in RFC 3339 format
metadatastringuser-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.
protostringtunnel protocol for ephemeral tunnels. one of http, https, tcp or tls
regionstringidentifier of tune region where the tunnel is running
tunnel_sessionRefreference object pointing to the tunnel session on which this tunnel was started
endpointRefthe ephemeral endpoint this tunnel is associated with, if this is an agent-initiated tunnel
labelsMap<string, string>the labels the tunnel group backends will match against, if this is a backend tunnel
backendsReftunnel group backends served by this backend tunnel
forwards_tostringupstream address the ngrok agent forwards traffic over this tunnel to. this may be expressed as a URL or a network address.

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource