Skip to content
Cloudflare API
Start here
API Reference
Zero Trust
Tunnels

List All Tunnels

client.zeroTrust.tunnels.list(TunnelListParams { account_id, exclude_prefix, existed_at, 10 more } params, RequestOptionsoptions?): V4PagePaginationArray<TunnelListResponse>
GET/accounts/{account_id}/tunnels

Lists and filters all types of Tunnels in an account.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
Cloudflare One Connectors WriteCloudflare One Connectors ReadCloudflare One Connector: cloudflared WriteCloudflare One Connector: cloudflared ReadCloudflare Tunnel WriteCloudflare Tunnel Read
ParametersExpand Collapse
params: TunnelListParams { account_id, exclude_prefix, existed_at, 10 more }
account_id: string

Path param: Cloudflare account ID

maxLength32
exclude_prefix?: string

Query param

existed_at?: string

Query param: If provided, include only resources that were created (and not deleted) before this time. URL encoded.

formaturl-encoded-date-time
include_prefix?: string

Query param

is_deleted?: boolean

Query param: If true, only include deleted tunnels. If false, exclude deleted tunnels. If empty, all tunnels will be included.

name?: string

Query param: A user-friendly name for the tunnel.

page?: number

Query param: Page number of paginated results.

minimum1
per_page?: number

Query param: Number of results to display.

maximum1000
minimum1
status?: "inactive" | "degraded" | "healthy" | "down"

Query param: The status of the tunnel. Valid values are inactive (tunnel has never been run), degraded (tunnel is active and able to serve traffic but in an unhealthy state), healthy (tunnel is active and able to serve traffic), or down (tunnel can not serve traffic as it has no connections to the Cloudflare Edge).

One of the following:
"inactive"
"degraded"
"healthy"
"down"
tun_types?: Array<"cfd_tunnel" | "warp_connector" | "warp" | 4 more>

Query param: The types of tunnels to filter by, separated by commas.

One of the following:
"cfd_tunnel"
"warp_connector"
"warp"
"magic"
"ip_sec"
"gre"
"cni"
uuid?: string

Query param: UUID of the tunnel.

formatuuid
maxLength36
was_active_at?: string

Query param

formatdate-time
was_inactive_at?: string

Query param

formatdate-time
ReturnsExpand Collapse
TunnelListResponse = CloudflareTunnel { id, account_tag, config_src, 10 more } | TunnelWARPConnectorTunnel { id, account_tag, connections, 8 more }

A Cloudflare Tunnel that connects your origin to Cloudflare's edge.

One of the following:
CloudflareTunnel { id, account_tag, config_src, 10 more }

A Cloudflare Tunnel that connects your origin to Cloudflare's edge.

id?: string

UUID of the tunnel.

formatuuid
maxLength36
account_tag?: string

Cloudflare account ID

maxLength32
config_src?: "local" | "cloudflare"

Indicates if this is a locally or remotely configured tunnel. If local, manage the tunnel using a YAML file on the origin machine. If cloudflare, manage the tunnel on the Zero Trust dashboard.

One of the following:
"local"
"cloudflare"
Deprecatedconnections?: Array<Connection>
This field will start returning an empty array. To fetch the connections of a given tunnel, please use the dedicated endpoint `/accounts/{account_id}/{tunnel_type}/{tunnel_id}/connections`

The Cloudflare Tunnel connections between your origin and Cloudflare's edge.

id?: string

UUID of the Cloudflare Tunnel connection.

formatuuid
maxLength36
client_id?: string

UUID of the Cloudflare Tunnel connector.

formatuuid
maxLength36
client_version?: string

The cloudflared version used to establish this connection.

colo_name?: string

The Cloudflare data center used for this connection.

is_pending_reconnect?: boolean

Cloudflare continues to track connections for several minutes after they disconnect. This is an optimization to improve latency and reliability of reconnecting. If true, the connection has disconnected but is still being tracked. If false, the connection is actively serving traffic.

opened_at?: string

Timestamp of when the connection was established.

formatdate-time
origin_ip?: string

The public IP address of the host running cloudflared.

uuid?: string

UUID of the Cloudflare Tunnel connection.

formatuuid
maxLength36
conns_active_at?: string

Timestamp of when the tunnel established at least one connection to Cloudflare's edge. If null, the tunnel is inactive.

formatdate-time
conns_inactive_at?: string

Timestamp of when the tunnel became inactive (no connections to Cloudflare's edge). If null, the tunnel is active.

formatdate-time
created_at?: string

Timestamp of when the resource was created.

formatdate-time
deleted_at?: string

Timestamp of when the resource was deleted. If null, the resource has not been deleted.

formatdate-time
metadata?: unknown

Metadata associated with the tunnel.

name?: string

A user-friendly name for a tunnel.

Deprecatedremote_config?: boolean
Use the config_src field instead.

If true, the tunnel can be configured remotely from the Zero Trust dashboard. If false, the tunnel must be configured locally on the origin machine.

status?: "inactive" | "degraded" | "healthy" | "down"

The status of the tunnel. Valid values are inactive (tunnel has never been run), degraded (tunnel is active and able to serve traffic but in an unhealthy state), healthy (tunnel is active and able to serve traffic), or down (tunnel can not serve traffic as it has no connections to the Cloudflare Edge).

One of the following:
"inactive"
"degraded"
"healthy"
"down"
tun_type?: "cfd_tunnel" | "warp_connector" | "warp" | 4 more

The type of tunnel.

One of the following:
"cfd_tunnel"
"warp_connector"
"warp"
"magic"
"ip_sec"
"gre"
"cni"
TunnelWARPConnectorTunnel { id, account_tag, connections, 8 more }

A Warp Connector Tunnel that connects your origin to Cloudflare's edge.

id?: string

UUID of the tunnel.

formatuuid
maxLength36
account_tag?: string

Cloudflare account ID

maxLength32
Deprecatedconnections?: Array<Connection>
This field will start returning an empty array. To fetch the connections of a given tunnel, please use the dedicated endpoint `/accounts/{account_id}/{tunnel_type}/{tunnel_id}/connections`

The Cloudflare Tunnel connections between your origin and Cloudflare's edge.

id?: string

UUID of the Cloudflare Tunnel connection.

formatuuid
maxLength36
client_id?: string

UUID of the Cloudflare Tunnel connector.

formatuuid
maxLength36
client_version?: string

The cloudflared version used to establish this connection.

colo_name?: string

The Cloudflare data center used for this connection.

is_pending_reconnect?: boolean

Cloudflare continues to track connections for several minutes after they disconnect. This is an optimization to improve latency and reliability of reconnecting. If true, the connection has disconnected but is still being tracked. If false, the connection is actively serving traffic.

opened_at?: string

Timestamp of when the connection was established.

formatdate-time
origin_ip?: string

The public IP address of the host running cloudflared.

uuid?: string

UUID of the Cloudflare Tunnel connection.

formatuuid
maxLength36
conns_active_at?: string

Timestamp of when the tunnel established at least one connection to Cloudflare's edge. If null, the tunnel is inactive.

formatdate-time
conns_inactive_at?: string

Timestamp of when the tunnel became inactive (no connections to Cloudflare's edge). If null, the tunnel is active.

formatdate-time
created_at?: string

Timestamp of when the resource was created.

formatdate-time
deleted_at?: string

Timestamp of when the resource was deleted. If null, the resource has not been deleted.

formatdate-time
metadata?: unknown

Metadata associated with the tunnel.

name?: string

A user-friendly name for a tunnel.

status?: "inactive" | "degraded" | "healthy" | "down"

The status of the tunnel. Valid values are inactive (tunnel has never been run), degraded (tunnel is active and able to serve traffic but in an unhealthy state), healthy (tunnel is active and able to serve traffic), or down (tunnel can not serve traffic as it has no connections to the Cloudflare Edge).

One of the following:
"inactive"
"degraded"
"healthy"
"down"
tun_type?: "cfd_tunnel" | "warp_connector" | "warp" | 4 more

The type of tunnel.

One of the following:
"cfd_tunnel"
"warp_connector"
"warp"
"magic"
"ip_sec"
"gre"
"cni"

List All Tunnels

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const tunnelListResponse of client.zeroTrust.tunnels.list({
  account_id: '699d98642c564d2e855e9661899b7252',
})) {
  console.log(tunnelListResponse);
}
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
      "account_tag": "699d98642c564d2e855e9661899b7252",
      "config_src": "cloudflare",
      "connections": [
        {
          "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "client_version": "2022.7.1",
          "colo_name": "DFW",
          "is_pending_reconnect": false,
          "opened_at": "2021-01-25T18:22:34.317854Z",
          "origin_ip": "10.1.0.137",
          "uuid": "1bedc50d-42b3-473c-b108-ff3d10c0d925"
        }
      ],
      "conns_active_at": "2009-11-10T23:00:00Z",
      "conns_inactive_at": "2009-11-10T23:00:00Z",
      "created_at": "2021-01-25T18:22:34.317854Z",
      "deleted_at": "2009-11-10T23:00:00.000000Z",
      "metadata": {},
      "name": "blog",
      "remote_config": true,
      "status": "healthy",
      "tun_type": "cfd_tunnel"
    }
  ],
  "success": true,
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}
Returns Examples
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
      "account_tag": "699d98642c564d2e855e9661899b7252",
      "config_src": "cloudflare",
      "connections": [
        {
          "id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "client_id": "1bedc50d-42b3-473c-b108-ff3d10c0d925",
          "client_version": "2022.7.1",
          "colo_name": "DFW",
          "is_pending_reconnect": false,
          "opened_at": "2021-01-25T18:22:34.317854Z",
          "origin_ip": "10.1.0.137",
          "uuid": "1bedc50d-42b3-473c-b108-ff3d10c0d925"
        }
      ],
      "conns_active_at": "2009-11-10T23:00:00Z",
      "conns_inactive_at": "2009-11-10T23:00:00Z",
      "created_at": "2021-01-25T18:22:34.317854Z",
      "deleted_at": "2009-11-10T23:00:00.000000Z",
      "metadata": {},
      "name": "blog",
      "remote_config": true,
      "status": "healthy",
      "tun_type": "cfd_tunnel"
    }
  ],
  "success": true,
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}