pipecat-ai · mattshep · Apr 20, 2026
diff --git a/api-reference/cli/cloud/deploy.mdx b/api-reference/cli/cloud/deploy.mdx
@@ -76,6 +76,17 @@ In addition to this flag, you also need to enable the `KrispVivaFilter()` for yo
 
 </ParamField>
 
+<ParamField path="--max-session-duration" type="number">
+  Maximum session duration in seconds. When a session reaches this limit, the
+  agent's connection is forcibly closed — the session is cut off mid-flight
+  with no notice to the bot. Valid range: `60` to `14400` (4 hours). Defaults
+  to `7200` (2 hours) when unset.
+
+See [Session duration limits](/pipecat-cloud/fundamentals/active-sessions#session-duration-limits)
+for more information.
+
+</ParamField>
+
 <ParamField path="--profile / -p" type="string" default="agent-1x">
   The agent profile to use for resource allocation. Valid values are:
   `agent-1x`, `agent-2x`, `agent-3x`.
@@ -92,8 +103,8 @@ See [Agent Profiles](/pipecat-cloud/fundamentals/deploy#agent-profiles) for more
 
 <ParamField path="--force / -f" type="boolean" default="false">
   Force a new deployment even if the configuration hasn't changed, replacing all
-  running pods. Useful for picking up updated container images when using mutable
-  tags like `latest`, or for refreshing modified secret values.
+  running pods. Useful for picking up updated container images when using
+  mutable tags like `latest`, or for refreshing modified secret values.
 </ParamField>
 
 <ParamField path="--yes / -y" type="boolean" default="false">
@@ -166,6 +177,12 @@ pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --
 pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --krisp-viva-audio-filter tel
 ```
 
+**Cap session duration (useful as a safety net for short-interaction agents):**
+
+```shell
+pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --max-session-duration 300
+```
+
 **Deploy using cloud build (interactive):**
 
 ```shell
@@ -293,6 +310,19 @@ agent_profile = "agent-2x"
 
 </ParamField>
 
+<ParamField path="max_session_duration" type="number" default="7200">
+Maximum session duration in seconds. When a session reaches this limit, the
+agent's connection is forcibly closed — the session is cut off mid-flight
+with no notice to the bot. Valid range: `60` to `14400` (4 hours). See
+[Session duration limits](/pipecat-cloud/fundamentals/active-sessions#session-duration-limits)
+for more information.
+
+```toml
+max_session_duration = 300
+```
+
+</ParamField>
+
 #### Scaling Configuration
 
 Define auto-scaling behavior in a `[scaling]` section:

diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-agent-create.json b/api-reference/pipecat-cloud/rest-reference/openapi-agent-create.json
@@ -42,7 +42,8 @@
                 "krispViva": {
                   "audioFilter": "tel"
                 },
-                "agentProfile": "agent-1x"
+                "agentProfile": "agent-1x",
+                "maxSessionDuration": 3600
               }
             }
           }
@@ -98,7 +99,8 @@
                         },
                         "krispViva": {
                           "audioFilters": true
-                        }
+                        },
+                        "maxSessionDurationSeconds": 3600
                       }
                     },
                     "serviceId": "b59a68ee-61c8-4d99-9ceb-e99a3953bdac",
@@ -301,6 +303,14 @@
             "enum": ["agent-1x", "agent-2x", "agent-3x"],
             "default": "agent-1x",
             "example": "agent-1x"
+          },
+          "maxSessionDuration": {
+            "type": "integer",
+            "description": "Maximum session duration in seconds. When a session reaches this limit, the agent's connection is forcibly closed — the session is cut off mid-flight with no notice to the bot. Valid range: 60 to 14400 (4 hours). Defaults to 7200 (2 hours) when unset.",
+            "minimum": 60,
+            "maximum": 14400,
+            "default": 7200,
+            "example": 3600
           }
         }
       },
@@ -464,6 +474,10 @@
                             "description": "Whether Krisp VIVA audio filters are enabled"
                           }
                         }
+                      },
+                      "maxSessionDurationSeconds": {
+                        "type": "integer",
+                        "description": "Maximum session duration in seconds configured for this service. Absent when the service is using the platform default."
                       }
                     }
                   }

diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-agent-update.json b/api-reference/pipecat-cloud/rest-reference/openapi-agent-update.json
@@ -51,7 +51,8 @@
                 "krispViva": {
                   "audioFilter": "tel"
                 },
-                "agentProfile": "agent-1x"
+                "agentProfile": "agent-1x",
+                "maxSessionDuration": 3600
               }
             }
           }
@@ -107,7 +108,8 @@
                         },
                         "krispViva": {
                           "audioFilters": true
-                        }
+                        },
+                        "maxSessionDurationSeconds": 3600
                       }
                     },
                     "serviceId": "b59a68ee-61c8-4d99-9ceb-e99a3953bdac",
@@ -297,7 +299,8 @@
                         },
                         "krispViva": {
                           "audioFilters": true
-                        }
+                        },
+                        "maxSessionDurationSeconds": 3600
                       }
                     },
                     "serviceId": "b59a68ee-61c8-4d99-9ceb-e99a3953bdac",
@@ -505,6 +508,14 @@
             "description": "Force a new deployment even if the configuration hasn't changed. Useful for picking up updated container images when using mutable tags like `latest`, or for refreshing modified secret values.",
             "default": false,
             "example": true
+          },
+          "maxSessionDuration": {
+            "type": "integer",
+            "description": "Maximum session duration in seconds. When a session reaches this limit, the agent's connection is forcibly closed — the session is cut off mid-flight with no notice to the bot. Valid range: 60 to 14400 (4 hours). Defaults to 7200 (2 hours) when unset.",
+            "minimum": 60,
+            "maximum": 14400,
+            "default": 7200,
+            "example": 3600
           }
         }
       },
@@ -667,6 +678,10 @@
                             "description": "Whether Krisp VIVA audio filters are enabled"
                           }
                         }
+                      },
+                      "maxSessionDurationSeconds": {
+                        "type": "integer",
+                        "description": "Maximum session duration in seconds configured for this service. Absent when the service is using the platform default."
                       }
                     }
                   }

diff --git a/pipecat-cloud/fundamentals/active-sessions.mdx b/pipecat-cloud/fundamentals/active-sessions.mdx
@@ -306,6 +306,46 @@ pipecat cloud agent stop my-first-agent --session [session-id]
 
 Deleting an agent deployment will block any new sessions from starting, but will not stop any active sessions. You must stop each session individually.
 
+## Session duration limits
+
+Every service has a maximum session duration. When a session reaches this limit, its connection is forcibly closed — the session is cut off mid-flight with no notice to the bot. This is a platform-level safeguard, not a polite signal: the bot code receives a connection error the next time it tries to send or receive data. If you want the bot to say goodbye gracefully before the cap, you must implement your own timer in bot code that fires slightly earlier.
+
+By default, sessions are capped at **7200 seconds (2 hours)**. You can configure this per service between **60 seconds** and **14400 seconds (4 hours)**:
+
+- **Increase** the limit for agents that routinely run long (e.g. interview, tutoring, or support calls that legitimately last 3+ hours).
+- **Decrease** the limit as a cost safety net — for example, if your application is meant to have 60-second calls, capping sessions at 120s protects you from runaway sessions caused by bugs in your agent code.
+
+<Tabs>
+  <Tab title="CLI">
+    ```shell
+    pipecat cloud deploy my-agent your-docker-repository/my-agent:0.1 --max-session-duration 300
+    ```
+
+    See [`--max-session-duration`](/api-reference/cli/cloud/deploy#max-session-duration) for details.
+
+  </Tab>
+  <Tab title="REST API">
+    ```bash
+    curl -X POST 'https://api.pipecat.daily.co/v1/agents/my-agent' \
+      -H 'Authorization: Bearer PRIVATE_API_KEY' \
+      -H 'Content-Type: application/json' \
+      -d '{"maxSessionDuration": 300}'
+    ```
+
+    See the [agent update endpoint](/api-reference/pipecat-cloud/rest-reference/endpoint/agent-update) for the full schema.
+
+  </Tab>
+  <Tab title="Dashboard">
+    Set the **Max session duration** field on your service's settings page in the [Dashboard <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://pipecat.daily.co).
+  </Tab>
+</Tabs>
+
+<Note>
+  Changing the max session duration triggers a new deployment of your service,
+  which replaces all running pods. Existing sessions running under the previous
+  configuration will continue to their original cap.
+</Note>
+
 ## Usage
 
 You are charged for the duration of each session, see [pricing](https://www.daily.co/pricing/pipecat-cloud).

diff --git a/pipecat-cloud/guides/capacity-planning.mdx b/pipecat-cloud/guides/capacity-planning.mdx
@@ -75,6 +75,7 @@ To determine the optimal reserved instance count for your deployment, consider:
 - **Development/Testing**: Use `min-agents: 0` to minimize costs during development
 - **Production Voice AI**: Set `min-agents` to cover your baseline traffic to avoid cold starts
 - **Time-Based Scaling**: Consider modifying your reserved count for known high-traffic periods
+- **Cap session duration**: Use [`--max-session-duration`](/api-reference/cli/cloud/deploy#max-session-duration) as a safety net against runaway sessions. If your application's calls are meant to be short, setting a tight cap (e.g. 120s for a 60s use case) prevents a buggy bot from racking up hours of charges.
 - **Monitoring**: Regularly review your warm capacity utilization to optimize your configuration
 
 <Info>A cold start typically takes around 10 seconds.</Info>