Send work heartbeat

POST /api/v1/cloud/environments/{environment_id}/work/{work_id}/heartbeat Sends a heartbeat for a work item and extends the worker lease. The first successful heartbeat moves a starting item to active. Use expected_last_heartbeat for optimistic lease ownership. If another worker has taken over the item, the precondition fails with 412.

Path parameters

Parameter	Type	Description
`environment_id`	string	Environment ID with the `env_` prefix
`work_id`	string	Work item ID with the `work_` prefix

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer $QODER_PAT`

Query parameters

Parameter	Type	Required	Description
`expected_last_heartbeat`	string	No	Either `NO_HEARTBEAT` or the last heartbeat timestamp returned by the server. Omit for an unconditional update
`desired_ttl_seconds`	integer	No	Desired lease TTL. Must be positive; accepted values are clamped to the supported range of 10 to 600 seconds

Example request

curl -X POST "https://api.qoder.com/api/v1/cloud/environments/env_019e64e01a137caf953ac2ac7b42ec5c/work/work_019f3be4fd2475d9a784bf2c739e1194/heartbeat?expected_last_heartbeat=NO_HEARTBEAT&desired_ttl_seconds=60" \
  -H "Authorization: Bearer $QODER_PAT"

Example response

HTTP 200 OK

{
  "type": "work_heartbeat",
  "last_heartbeat": "2026-07-01T08:15:06.120394Z",
  "lease_extended": true,
  "state": "active",
  "ttl_seconds": 60
}

Response fields

Returns a Work heartbeat object.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	`desired_ttl_seconds` is not a positive integer
400	`invalid_request_error`	`expected_last_heartbeat` is neither `NO_HEARTBEAT` nor an RFC 3339 timestamp
400	`invalid_request_error`	The Environment is not `self_hosted`
401	`authentication_error`	PAT invalid or expired
403	`permission_error`	Not authorized for this operation
404	`not_found_error`	Environment or work item not found
409	`invalid_request_error`	Work item is `queued` or `stopped` and cannot be heartbeated
412	`precondition_failed_error`	`expected_last_heartbeat` does not match the current lease owner

See Errors for the full error envelope.

Cloud environment setup

Choose the container, network, and dependencies your agent runs in.

​Path parameters

​Headers

​Query parameters

​Example request

​Example response

​Response fields

​Errors

​Related