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

{
    "tunnels": [
        {
            "id": "tn_2TMGH0ybZBbfx1JqjUyEUbF0mBU",
            "public_url": "https://eae72ddee951.ngrok.paid",
            "started_at": "2023-07-31T23:17:24Z",
            "proto": "https",
            "region": "us",
            "tunnel_session": {
                "id": "ts_2TMGH5pURxBRFkvbgAy2558Pm9n",
                "uri": "https://api.ngrok.com/tunnel_sessions/ts_2TMGH5pURxBRFkvbgAy2558Pm9n"
            },
            "endpoint": {
                "id": "ep_2TMGH0ybZBbfx1JqjUyEUbF0mBU",
                "uri": "https://api.ngrok.com/endpoints/ep_2TMGH0ybZBbfx1JqjUyEUbF0mBU"
            },
            "forwards_to": "http://localhost:80"
        },
        {
            "id": "tn_2TMGGRKTToNnKm5ZmGoVv4qLmSi",
            "public_url": "://:0",
            "started_at": "2023-07-31T23:17:19Z",
            "region": "us",
            "tunnel_session": {
                "id": "ts_2TMGGQk5w8vCXnNM4UGNs0sZVsf",
                "uri": "https://api.ngrok.com/tunnel_sessions/ts_2TMGGQk5w8vCXnNM4UGNs0sZVsf"
            },
            "labels": {
                "baz": "qux",
                "foo": "bar"
            },
            "forwards_to": "http://localhost:80"
        }
    ],
    "uri": "https://api.ngrok.com/tunnels",
    "next_page_uri": null
}

Fields

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

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

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_2TMGH0ybZBbfx1JqjUyEUbF0mBU

Response

Returns a 200 response on success

Example Response

{
    "id": "tn_2TMGH0ybZBbfx1JqjUyEUbF0mBU",
    "public_url": "https://eae72ddee951.ngrok.paid",
    "started_at": "2023-07-31T23:17:24Z",
    "proto": "https",
    "region": "us",
    "tunnel_session": {
        "id": "ts_2TMGH5pURxBRFkvbgAy2558Pm9n",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_2TMGH5pURxBRFkvbgAy2558Pm9n"
    },
    "endpoint": {
        "id": "ep_2TMGH0ybZBbfx1JqjUyEUbF0mBU",
        "uri": "https://api.ngrok.com/endpoints/ep_2TMGH0ybZBbfx1JqjUyEUbF0mBU"
    },
    "forwards_to": "http://localhost:80"
}

Fields

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

id	string	a resource identifier
uri	string	a uri for locating a resource