API Reference

Zero Trust

Tunnels

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List All Tunnels

client.ZeroTrust.Tunnels.List(ctx, params) (*V4PagePaginationArray[TunnelListResponse], error)

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

AccountID param.Field[string]

Path param: Cloudflare account ID

maxLength32

ExcludePrefix param.Field[string]optional

Query param

ExistedAt param.Field[string]optional

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

formaturl-encoded-date-time

IncludePrefix param.Field[string]optional

Query param

IsDeleted param.Field[bool]optional

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

Name param.Field[string]optional

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

Page param.Field[float64]optional

Query param: Page number of paginated results.

minimum1

PerPage param.Field[float64]optional

Query param: Number of results to display.

maximum1000

minimum1

Status param.Field[TunnelListParamsStatus]optional

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).

const TunnelListParamsStatusInactive TunnelListParamsStatus = "inactive"

const TunnelListParamsStatusDegraded TunnelListParamsStatus = "degraded"

const TunnelListParamsStatusHealthy TunnelListParamsStatus = "healthy"

const TunnelListParamsStatusDown TunnelListParamsStatus = "down"

TunTypes param.Field[[]TunnelListParamsTunType]optional

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

const TunnelListParamsTunTypeCfdTunnel TunnelListParamsTunType = "cfd_tunnel"

const TunnelListParamsTunTypeWARPConnector TunnelListParamsTunType = "warp_connector"

const TunnelListParamsTunTypeWARP TunnelListParamsTunType = "warp"

const TunnelListParamsTunTypeMagic TunnelListParamsTunType = "magic"

const TunnelListParamsTunTypeIPSec TunnelListParamsTunType = "ip_sec"

const TunnelListParamsTunTypeGRE TunnelListParamsTunType = "gre"

const TunnelListParamsTunTypeCNI TunnelListParamsTunType = "cni"

UUID param.Field[string]optional

Query param: UUID of the tunnel.

formatuuid

maxLength36

WasActiveAt param.Field[Time]optional

Query param

formatdate-time

WasInactiveAt param.Field[Time]optional

Query param

formatdate-time

ReturnsExpand Collapse

type TunnelListResponse interface{…}

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

One of the following:

type CloudflareTunnel struct{…}

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

ID stringoptional

UUID of the tunnel.

formatuuid

maxLength36

AccountTag stringoptional

Cloudflare account ID

maxLength32

ConfigSrc CloudflareTunnelConfigSrcoptional

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:

const CloudflareTunnelConfigSrcLocal CloudflareTunnelConfigSrc = "local"

const CloudflareTunnelConfigSrcCloudflare CloudflareTunnelConfigSrc = "cloudflare"

DeprecatedConnections []CloudflareTunnelConnectionoptional

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 stringoptional

UUID of the Cloudflare Tunnel connection.

formatuuid

maxLength36

ClientID stringoptional

UUID of the Cloudflare Tunnel connector.

formatuuid

maxLength36

ClientVersion stringoptional

The cloudflared version used to establish this connection.

ColoName stringoptional

The Cloudflare data center used for this connection.

IsPendingReconnect booloptional

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.

OpenedAt Timeoptional

Timestamp of when the connection was established.

formatdate-time

OriginIP stringoptional

The public IP address of the host running cloudflared.

UUID stringoptional

UUID of the Cloudflare Tunnel connection.

formatuuid

maxLength36

ConnsActiveAt Timeoptional

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

formatdate-time

ConnsInactiveAt Timeoptional

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

formatdate-time

CreatedAt Timeoptional

Timestamp of when the resource was created.

formatdate-time

DeletedAt Timeoptional

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

formatdate-time

Metadata unknownoptional

Metadata associated with the tunnel.

Name stringoptional

A user-friendly name for a tunnel.

DeprecatedRemoteConfig booloptional

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 CloudflareTunnelStatusoptional

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:

const CloudflareTunnelStatusInactive CloudflareTunnelStatus = "inactive"

const CloudflareTunnelStatusDegraded CloudflareTunnelStatus = "degraded"

const CloudflareTunnelStatusHealthy CloudflareTunnelStatus = "healthy"

const CloudflareTunnelStatusDown CloudflareTunnelStatus = "down"

TunType CloudflareTunnelTunTypeoptional

The type of tunnel.

One of the following:

const CloudflareTunnelTunTypeCfdTunnel CloudflareTunnelTunType = "cfd_tunnel"

const CloudflareTunnelTunTypeWARPConnector CloudflareTunnelTunType = "warp_connector"

const CloudflareTunnelTunTypeWARP CloudflareTunnelTunType = "warp"

const CloudflareTunnelTunTypeMagic CloudflareTunnelTunType = "magic"

const CloudflareTunnelTunTypeIPSec CloudflareTunnelTunType = "ip_sec"

const CloudflareTunnelTunTypeGRE CloudflareTunnelTunType = "gre"

const CloudflareTunnelTunTypeCNI CloudflareTunnelTunType = "cni"

type TunnelListResponseTunnelWARPConnectorTunnel struct{…}

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

ID stringoptional

UUID of the tunnel.

formatuuid

maxLength36

AccountTag stringoptional

Cloudflare account ID

maxLength32

DeprecatedConnections []TunnelListResponseTunnelWARPConnectorTunnelConnectionoptional

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 stringoptional

UUID of the Cloudflare Tunnel connection.

formatuuid

maxLength36

ClientID stringoptional

UUID of the Cloudflare Tunnel connector.

formatuuid

maxLength36

ClientVersion stringoptional

The cloudflared version used to establish this connection.

ColoName stringoptional

The Cloudflare data center used for this connection.

IsPendingReconnect booloptional

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.

OpenedAt Timeoptional

Timestamp of when the connection was established.

formatdate-time

OriginIP stringoptional

The public IP address of the host running cloudflared.

UUID stringoptional

UUID of the Cloudflare Tunnel connection.

formatuuid

maxLength36

ConnsActiveAt Timeoptional

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

formatdate-time

ConnsInactiveAt Timeoptional

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

formatdate-time

CreatedAt Timeoptional

Timestamp of when the resource was created.

formatdate-time

DeletedAt Timeoptional

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

formatdate-time

Metadata unknownoptional

Metadata associated with the tunnel.

Name stringoptional

A user-friendly name for a tunnel.

Status TunnelListResponseTunnelWARPConnectorTunnelStatusoptional

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:

const TunnelListResponseTunnelWARPConnectorTunnelStatusInactive TunnelListResponseTunnelWARPConnectorTunnelStatus = "inactive"

const TunnelListResponseTunnelWARPConnectorTunnelStatusDegraded TunnelListResponseTunnelWARPConnectorTunnelStatus = "degraded"

const TunnelListResponseTunnelWARPConnectorTunnelStatusHealthy TunnelListResponseTunnelWARPConnectorTunnelStatus = "healthy"

const TunnelListResponseTunnelWARPConnectorTunnelStatusDown TunnelListResponseTunnelWARPConnectorTunnelStatus = "down"

TunType TunnelListResponseTunnelWARPConnectorTunnelTunTypeoptional

The type of tunnel.

One of the following:

const TunnelListResponseTunnelWARPConnectorTunnelTunTypeCfdTunnel TunnelListResponseTunnelWARPConnectorTunnelTunType = "cfd_tunnel"

const TunnelListResponseTunnelWARPConnectorTunnelTunTypeWARPConnector TunnelListResponseTunnelWARPConnectorTunnelTunType = "warp_connector"

const TunnelListResponseTunnelWARPConnectorTunnelTunTypeWARP TunnelListResponseTunnelWARPConnectorTunnelTunType = "warp"

const TunnelListResponseTunnelWARPConnectorTunnelTunTypeMagic TunnelListResponseTunnelWARPConnectorTunnelTunType = "magic"

const TunnelListResponseTunnelWARPConnectorTunnelTunTypeIPSec TunnelListResponseTunnelWARPConnectorTunnelTunType = "ip_sec"

const TunnelListResponseTunnelWARPConnectorTunnelTunTypeGRE TunnelListResponseTunnelWARPConnectorTunnelTunType = "gre"

const TunnelListResponseTunnelWARPConnectorTunnelTunTypeCNI TunnelListResponseTunnelWARPConnectorTunnelTunType = "cni"

List All Tunnels

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/option"
  "github.com/cloudflare/cloudflare-go/zero_trust"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.ZeroTrust.Tunnels.List(context.TODO(), zero_trust.TunnelListParams{
    AccountID: cloudflare.F("699d98642c564d2e855e9661899b7252"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

200 example

{
  "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

200 example

{
  "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
  }
}