​
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_32ELFeTyzStvllGupngXcSO5GUy",
        "uri": "https://api.ngrok.com/endpoints/ep_32ELFeTyzStvllGupngXcSO5GUy"
      },
      "forwards_to": "http://localhost:80",
      "id": "tn_32ELFeTyzStvllGupngXcSO5GUy",
      "proto": "https",
      "public_url": "https://307ddb3e6b10.ngrok.paid",
      "region": "us",
      "started_at": "2025-09-04T10:11:22Z",
      "tunnel_session": {
        "id": "ts_32ELFiDEVP0MLVPxhqpmwXCxldd",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_32ELFiDEVP0MLVPxhqpmwXCxldd"
      }
    },
    {
      "forwards_to": "http://localhost:80",
      "id": "tn_32ELF3tMdLHH7aoMdw8yw0zMhoJ",
      "labels": {
        "baz": "qux",
        "foo": "bar"
      },
      "region": "us",
      "started_at": "2025-09-04T10:11:17Z",
      "tunnel_session": {
        "id": "ts_32ELF2NjfB7chY8ujc37f615rVM",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_32ELF2NjfB7chY8ujc37f615rVM"
      }
    }
  ],
  "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_32ELFeTyzStvllGupngXcSO5GUy

​
Response

Returns a 200 response on success

​
Example Response

{
  "endpoint": {
    "id": "ep_32ELFeTyzStvllGupngXcSO5GUy",
    "uri": "https://api.ngrok.com/endpoints/ep_32ELFeTyzStvllGupngXcSO5GUy"
  },
  "forwards_to": "http://localhost:80",
  "id": "tn_32ELFeTyzStvllGupngXcSO5GUy",
  "proto": "https",
  "public_url": "https://307ddb3e6b10.ngrok.paid",
  "region": "us",
  "started_at": "2025-09-04T10:11:22Z",
  "tunnel_session": {
    "id": "ts_32ELFiDEVP0MLVPxhqpmwXCxldd",
    "uri": "https://api.ngrok.com/tunnel_sessions/ts_32ELFiDEVP0MLVPxhqpmwXCxldd"
  }
}

​
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