Tunnel: New default for list API endpoints

Author: nikitacano

src/content/changelog/cloudflare-tunnel/2025-09-01-tunnel-list-list-endpoints-new-default.mdx

@@ -0,0 +1,42 @@
+---
+title: Cloudflare Tunnel list endpoints will no longer return deleted resources by default starting December 1, 2025
+description: The is_deleted parameter for specific Cloudflare Tunnel list API endpoints will default to false. To retrieve deleted tunnels, you must explicitly set this parameter to true.
+hidden: false
+date: 2025-09-01
+---
+
+Starting **December 1, 2025**, [Cloudflare Tunnel API](/api/resources/zero_trust/subresources/tunnels/) list endpoints will no longer return deleted tunnels by default. This change makes the API behavior more intuitive by only returning active resources unless otherwise specified. No action is required if you already explicitly set `is_deleted=false` or if you only need to list active tunnels.
+
+This change affects the following API endpoints:
+* [`GET /accounts/{account_id}/tunnels`](/api/resources/zero_trust/subresources/tunnels/methods/list/)
+* [`GET /accounts/{account_id}/cfd_tunnel`](/api/resources/zero_trust/subresources/tunnels/subresources/cloudflared/methods/list/)
+* [`GET /accounts/{account_id}/warp_connector`](/api/resources/zero_trust/subresources/tunnels/subresources/warp_connector/methods/list/)
+
+## What is changing?
+
+The default behavior of the `is_deleted` query parameter will be updated.
+
+| Scenario | Previous Behavior (before December 1, 2025) | New Behavior (from December 1, 2025) |
+| :--- | :--- | :--- |
+| `is_deleted` parameter is omitted | Returns **active & deleted** tunnels | Returns **only active** tunnels |
+
+
+## Action required
+
+If you need to retrieve deleted tunnels, please update your API calls to explicitly include the `is_deleted` parameter before **December 1, 2025**.
+
+```bash
+# To get ONLY deleted tunnels
+curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tunnels?is_deleted=true" \
+     -H "Authorization: Bearer $API_TOKEN"
+```
+
+No action is required if you only need to list active tunnels.
+
+## Why we’re making this change
+This update is based on user feedback and aims to:
+* **Create a more intuitive default:** Aligning with common API design principles where list operations return only active resources by default.
+* **Reduce unexpected results:** Prevents users from accidentally operating on deleted tunnels that were returned unexpectedly.
+* **Improve performance:** For most users, the default query result will now be smaller and more relevant.
+
+To learn more, please visit the [Cloudflare Tunnel API documentation](/api/resources/zero_trust/subresources/tunnels/).