> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Work heartbeat の送信

> セルフホスト work item のリースを延長します。

`POST /api/v1/cloud/environments/{environment_id}/work/{work_id}/heartbeat`

work item の heartbeat を送信し、worker のリースを延長します。最初に成功した heartbeat は `starting` のアイテムを `active` へ移行させます。

楽観的なリース所有権のために `expected_last_heartbeat` を使用します。別の worker がアイテムを引き継いでいる場合、事前条件は 412 で失敗します。

## パスパラメータ

| パラメータ            | 型      | 説明                               |
| ---------------- | ------ | -------------------------------- |
| `environment_id` | string | `env_` プレフィックス付きの Environment ID |
| `work_id`        | string | `work_` プレフィックス付きの Work item ID  |

## リクエストヘッダー

| ヘッダー            | 必須 | 説明                  |
| --------------- | -- | ------------------- |
| `Authorization` | はい | `Bearer $QODER_PAT` |

## クエリパラメータ

| パラメータ                     | 型       | 必須  | 説明                                                               |
| ------------------------- | ------- | --- | ---------------------------------------------------------------- |
| `expected_last_heartbeat` | string  | いいえ | `NO_HEARTBEAT` またはサーバーが返した最後の heartbeat タイムスタンプのいずれか。無条件更新の場合は省略 |
| `desired_ttl_seconds`     | integer | いいえ | 希望するリース TTL。正の値でなければならない。受け入れられた値はサポート範囲の 10 秒から 600 秒にクランプされる   |

## リクエスト例

```bash theme={null}
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"
```

## レスポンス例

**HTTP 200 OK**

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

## レスポンスフィールド

[Work heartbeat オブジェクト](/ja/cloud-agents/api/environments/work/schemas#work-heartbeat-object) を返します。

## エラー

| HTTP | type                        | トリガー                                                               |
| ---- | --------------------------- | ------------------------------------------------------------------ |
| 400  | `invalid_request_error`     | `desired_ttl_seconds` が正の整数でない                                     |
| 400  | `invalid_request_error`     | `expected_last_heartbeat` が `NO_HEARTBEAT` でも RFC 3339 タイムスタンプでもない |
| 400  | `invalid_request_error`     | Environment が `self_hosted` でない                                    |
| 401  | `authentication_error`      | PAT が無効または期限切れ                                                     |
| 403  | `permission_error`          | この操作の権限がない                                                         |
| 404  | `not_found_error`           | Environment または work item が存在しない                                   |
| 409  | `invalid_request_error`     | Work item が `queued` または `stopped` であり heartbeat できない              |
| 412  | `precondition_failed_error` | `expected_last_heartbeat` が現在のリース所有者と一致しない                         |

完全なエラーエンベロープについては [エラーリファレンス](/ja/cloud-agents/api/conventions/errors) を参照してください。

## 関連

<CardGroup cols={2}>
  <Card title="クラウド環境" icon="server" href="/ja/cloud-agents/environments">
    Agent が実行されるコンテナ、ネットワーク、依存関係を選択する。
  </Card>
</CardGroup>