Tunnel Sessions
List Tunnel Sessions
List all online tunnel sessions running on this account.
Request
GET /tunnel_sessions
Example Request
curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tunnel_sessions
Response
Returns a 200 response on success
Example Response
{
"tunnel_sessions": [
{
"agent_version": "3.1000.0-development",
"credential": {
"id": "cr_2TMGHUIT05DZp00MDukw6el2AXH",
"uri": "https://api.ngrok.com/credentials/cr_2TMGHUIT05DZp00MDukw6el2AXH"
},
"id": "ts_2TMGHdV3GP4glVpLYiyhFyhduiN",
"ip": "10.110.2.2",
"os": "linux",
"region": "us",
"started_at": "2023-07-31T23:17:29Z",
"transport": "ngrok/2",
"uri": "https://api.ngrok.com/tunnel_sessions/ts_2TMGHdV3GP4glVpLYiyhFyhduiN"
}
],
"uri": "https://api.ngrok.com/tunnel_sessions",
"next_page_uri": null
}
Fields
tunnel_sessions | TunnelSession | list of all tunnel sessions on this account |
uri | string | URI to the API resource of the tunnel session list |
next_page_uri | string | URI of the next page, or null if there is no next page |
TunnelSession fields
agent_version | string | version of the ngrok agent that started this ngrok tunnel session |
credential | Ref | reference to the tunnel credential or ssh credential used by the ngrok agent to start this tunnel session |
id | string | unique tunnel session resource identifier |
ip | string | source ip address of the tunnel session |
metadata | string | arbitrary user-defined data specified in the metadata property in the ngrok configuration file. See the metadata configuration option |
os | string | operating system of the host the ngrok agent is running on |
region | string | the ngrok region identifier in which this tunnel session was started |
started_at | string | time when the tunnel session first connected to the ngrok servers |
transport | string | the transport protocol used to start the tunnel session. Either ngrok/v2 or ssh |
uri | string | URI to the API resource of the tunnel session |
Ref fields
id | string | a resource identifier |
uri | string | a uri for locating a resource |
Get Tunnel Session
Get the detailed status of a tunnel session by ID
Request
GET /tunnel_sessions/{id}
Example Request
curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tunnel_sessions/ts_2TMGHdV3GP4glVpLYiyhFyhduiN
Response
Returns a 200 response on success
Example Response
{
"agent_version": "3.1000.0-development",
"credential": {
"id": "cr_2TMGHUIT05DZp00MDukw6el2AXH",
"uri": "https://api.ngrok.com/credentials/cr_2TMGHUIT05DZp00MDukw6el2AXH"
},
"id": "ts_2TMGHdV3GP4glVpLYiyhFyhduiN",
"ip": "10.110.2.2",
"os": "linux",
"region": "us",
"started_at": "2023-07-31T23:17:29Z",
"transport": "ngrok/2",
"uri": "https://api.ngrok.com/tunnel_sessions/ts_2TMGHdV3GP4glVpLYiyhFyhduiN"
}
Fields
agent_version | string | version of the ngrok agent that started this ngrok tunnel session |
credential | Ref | reference to the tunnel credential or ssh credential used by the ngrok agent to start this tunnel session |
id | string | unique tunnel session resource identifier |
ip | string | source ip address of the tunnel session |
metadata | string | arbitrary user-defined data specified in the metadata property in the ngrok configuration file. See the metadata configuration option |
os | string | operating system of the host the ngrok agent is running on |
region | string | the ngrok region identifier in which this tunnel session was started |
started_at | string | time when the tunnel session first connected to the ngrok servers |
transport | string | the transport protocol used to start the tunnel session. Either ngrok/v2 or ssh |
uri | string | URI to the API resource of the tunnel session |
Ref fields
id | string | a resource identifier |
uri | string | a uri for locating a resource |
Restart Tunnel Agent
Issues a command instructing the ngrok agent to restart. The agent restarts itself by calling exec() on platforms that support it. This operation is notably not supported on Windows. When an agent restarts, it reconnects with a new tunnel session ID.
Request
POST /tunnel_sessions/{id}/restart
Example Request
curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/tunnel_sessions/ts_1vcl4fYZxXY0zNFbpCloylDCG0S/restart
Parameters
id | string | a resource identifier |
Response
Returns a 204 response with no body on success
Stop Tunnel Agent
Issues a command instructing the ngrok agent that started this tunnel session to exit.
Request
POST /tunnel_sessions/{id}/stop
Example Request
curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/tunnel_sessions/ts_1vcl4fYZxXY0zNFbpCloylDCG0S/stop
Parameters
id | string | a resource identifier |
Response
Returns a 204 response with no body on success
Update Tunnel Agent
Issues a command instructing the ngrok agent to update itself to the latest version. After this call completes successfully, the ngrok agent will be in the update process. A caller should wait some amount of time to allow the update to complete (at least 10 seconds) before making a call to the Restart endpoint to request that the agent restart itself to start using the new code. This call will never update an ngrok agent to a new major version which could cause breaking compatibility issues. If you wish to update to a new major version, that must be done manually. Still, please be aware that updating your ngrok agent could break your integration. This call will fail in any of the following circumstances: there is no update available the ngrok agent's configuration disabled update checks the agent is currently in process of updating the agent has already successfully updated but has not yet been restarted
Request
POST /tunnel_sessions/{id}/update
Example Request
curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/tunnel_sessions/ts_1vcl4fYZxXY0zNFbpCloylDCG0S/update
Parameters
id | string |
Response
Returns a 204 response with no body on success