diff --git a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx
index 03c4115c40d..f2e3e1c0660 100644
--- a/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx
+++ b/packages/web/docs/src/content/router/configuration/traffic_shaping.mdx
@@ -30,13 +30,14 @@ Limits the maximum number of concurrent HTTP connections the router will open to
 host. This acts as a safeguard to prevent overwhelming a subgraph with too many simultaneous
 requests.
 
-### `pool_idle_timeout_seconds`
+### `pool_idle_timeout`
 
-- **Type:** `integer`
-- **Default:** `50`
+- **Type:** `string`
+- **Default:** `50s`
 
-Controls the timeout (in seconds) for idle keep-alive connections in the router's connection pool.
-Connections that are unused for this duration will be closed.
+Controls the timeout in duration string format (e.g. `1m` for 1 minute, `30s` for 30 seconds) for
+idle keep-alive connections in the router's connection pool. Connections that are unused for this
+duration will be closed.
 
 ## Example
 
@@ -47,5 +48,5 @@ longer idle timeout.
 traffic_shaping:
   dedupe_enabled: true
   max_connections_per_host: 250
-  pool_idle_timeout_seconds: 90
+  pool_idle_timeout: 90s
 ```
diff --git a/packages/web/docs/src/content/router/guides/performance-tuning.mdx b/packages/web/docs/src/content/router/guides/performance-tuning.mdx
index 9852fc95e03..1b93ced73b3 100644
--- a/packages/web/docs/src/content/router/guides/performance-tuning.mdx
+++ b/packages/web/docs/src/content/router/guides/performance-tuning.mdx
@@ -54,10 +54,13 @@ Start with the default and adjust based on your observations:
 
 ## Managing Idle Connections
 
-The `pool_idle_timeout_seconds` setting controls how long unused connections stay open in the
-router's connection pool before being closed.
+The `pool_idle_timeout` setting controls how long unused connections stay open in the router's
+connection pool before being closed.
 
-- **Default Value:** `50` seconds
+- **Default Value:** `50s`
+
+It takes a duration string (like `30s` for 30 seconds, or `1m` for 1 minute). This setting affects
+how aggressively the router reuses existing connections versus closing them to free up resources.
 
 ### The Connection Reuse Trade-off