diff --git a/api-reference/cli/cloud/deploy.mdx b/api-reference/cli/cloud/deploy.mdx
index b5c831c5..d8e59c30 100644
--- 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
+
+ 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.
+
+
+
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
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.
@@ -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"
+
+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
+```
+
+
+
#### 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
index 154baa77..1232e544 100644
--- 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
index a5fca8aa..203fc3ad 100644
--- 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
index e7314a9a..2263faf9 100644
--- 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.
+
+
+
+ ```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.
+
+
+
+ ```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.
+
+
+
+ Set the **Max session duration** field on your service's settings page in the [Dashboard ](https://pipecat.daily.co).
+
+
+
+
+ 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.
+
+
## 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
index 8b94d15c..3ea156e1 100644
--- 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
A cold start typically takes around 10 seconds.