Skip to main content
GET
/
v1
/
tunnels
List Tunnels
curl --request GET \
  --url https://api.example.com/v1/tunnels
{
  "id": "<string>",
  "hostname": "<string>",
  "slug": "<string>",
  "status": "<string>",
  "requestedPort": 123,
  "createdAt": "<string>",
  "lease": {
    "lease.lastHeartbeatAt": "<string>",
    "lease.expiresAt": "<string>"
  },
  "stoppedAt": "<string>",
  "lastError": "<string>"
}
Retrieve a list of all tunnels for the authenticated user.

​
Authentication

Requires a valid access token in the Authorization header: 
Authorization: Bearer <access_token>

​
Query Parameters

​
includeInactive
boolean
default:"false"
Whether to include inactive tunnels (stopped or failed) in the response.Accepts true, 1, false, or 0.

​
Response

Returns an array of tunnel objects:
​
id
string
UUID identifier for the tunnel.
​
hostname
string
The public hostname assigned to this tunnel.
​
slug
string
The subdomain slug used in the hostname.
​
status
string
Current status of the tunnel.
​
requestedPort
number
The local port number that this tunnel exposes.
​
createdAt
string
ISO 8601 timestamp when the tunnel was created.
​
lease
object
Heartbeat lease information. null if the tunnel has no active lease.
​
stoppedAt
string
ISO 8601 timestamp when the tunnel was stopped. null if still active.
​
lastError
string
Error message if the tunnel failed. null otherwise.

​
Example Request

curl -X GET https://api.example.com/v1/tunnels \
  -H "Authorization: Bearer <access_token>"

​
Example Response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "hostname": "my-app.example.com",
    "slug": "my-app",
    "status": "active",
    "requestedPort": 3000,
    "createdAt": "2026-03-05T10:30:00.000Z",
    "lease": {
      "lastHeartbeatAt": "2026-03-05T10:32:15.000Z",
      "expiresAt": "2026-03-05T10:33:15.000Z"
    },
    "stoppedAt": null,
    "lastError": null
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "hostname": "test-api.example.com",
    "slug": "test-api",
    "status": "stopped",
    "requestedPort": 8080,
    "createdAt": "2026-03-05T09:15:00.000Z",
    "lease": null,
    "stoppedAt": "2026-03-05T10:00:00.000Z",
    "lastError": null
  }
]

​
Usage Notes

By default, only active tunnels (active, creating, stopping) are returned. Use includeInactive=true to see your full tunnel history.
The lease object shows when the tunnel will expire if no heartbeat is received. Tunnels expire 60 seconds after the last heartbeat.

Build docs developers (and LLMs) love

Get started for freeTalk to us