Skip to main content
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

ParameterTypeDescription
environment_idstringEnvironment ID with the env_ prefix
work_idstringWork item ID with the work_ prefix

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer $QODER_PAT

​
Query parameters

ParameterTypeRequiredDescription
expected_last_heartbeatstringNoEither NO_HEARTBEAT or the last heartbeat timestamp returned by the server. Omit for an unconditional update
desired_ttl_secondsintegerNoDesired 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

HTTPTypeTrigger
400invalid_request_errordesired_ttl_seconds is not a positive integer
400invalid_request_errorexpected_last_heartbeat is neither NO_HEARTBEAT nor an RFC 3339 timestamp
400invalid_request_errorThe Environment is not self_hosted
401authentication_errorPAT invalid or expired
403permission_errorNot authorized for this operation
404not_found_errorEnvironment or work item not found
409invalid_request_errorWork item is queued or stopped and cannot be heartbeated
412precondition_failed_errorexpected_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.