talonic_heartbeat_decision_task
Extend the lease on a claimed decision task. The lease is short by design (120 seconds by default) so an abandoned claim frees quickly; a decision that takes longer keeps its claim alive by heartbeating before lease_expires_at. The lease never extends past sla_deadline_at — that is the hard decision deadline, after which the app's fallback policy applies.
| Parameter | Type | Description |
|---|---|---|
| task_id * | UUID | Claimed task ID. |
| execution_epoch * | integer | Exact epoch from the current claim. |
Heartbeat response
// talonic_heartbeat_decision_task({ "task_id": "11111111-1111-4111-8111-111111111111", "execution_epoch": 1 })
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "claimed",
"execution_epoch": 1,
"heartbeat_at": "2026-09-22T10:01:30.000Z",
"lease_expires_at": "2026-09-22T10:03:30.000Z",
"sla_deadline_at": "2026-09-22T10:10:00.000Z",
"...": "remaining metadata as in the list"
}Treat a failed heartbeat as a hard stop. HTTP 409 means the epoch is stale — the lease lapsed and the task was reclaimed, released, cancelled or timed out — so any decision you were forming belongs to a claim that no longer exists and will be rejected on submit. Discard it and return to talonic_list_decision_tasks.
Frequently asked questions
How often should an agent heartbeat a decision task?+
Comfortably inside the lease: with the default 120-second lease, roughly every 60 seconds while the decision is still being worked on. Stop once the task is submitted, released or failed.
Can a heartbeat extend past the SLA deadline?+
No. The lease is clamped to sla_deadline_at. If the decision cannot be made before then, submit what you have with an honest confidence, release the task, or fail it with a reason so the fallback policy runs deliberately rather than by timeout.