Timeouts
Every pause request has a configurable timeout. When the timeout fires, the pause moves from pending to timed_out.
Setting a Timeout#
Pass timeout_hours when creating a pause:
{
"timeout_hours": 4,
"timeout_default": "Reject"
}
timeout_hours: How many hours to wait before timing out. Must be a positive integer.timeout_default: Which option to auto-select when timeout fires. Optional.
timeout_default Behavior#
| Configuration | What happens on timeout |
|---|---|
timeout_default: "Reject" |
status → timed_out, response_choice → "Reject", response_at set |
timeout_default: null (default) |
status → timed_out, response_choice → null, response_at → null |
When timeout_default is set, your agent can treat the timeout the same as a normal response — just check response_choice.
When no default is set, your agent receives status: "timed_out" with response_choice: null and must handle this case explicitly.
Plan Limits on Timeout Duration#
| Plan | Max timeout_hours |
|---|---|
| Free | 24 (1 day) |
| Starter | 168 (7 days) |
| Pro | 720 (30 days) |
| Enterprise | Unlimited |
If you request a timeout_hours that exceeds your plan limit, it is silently capped to the plan maximum. It is not rejected as an error.
Webhook on Timeout#
If you have registered a webhook with "pause.timed_out" in the events list, it fires when the timeout processes. The payload includes the timeout_default value in data.choice (or null if not set).
Timeout Implementation#
A background worker sweeps for expired pauses every minute, so a timeout fires within about a minute of expires_at. The sweep only touches pauses still in pending; a pause that was answered or cancelled first is untouched. This design is durable across worker restarts, even for multi-day timeouts.