> ## 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 のポーリング

> セルフホスト Environment から利用可能な work item を 1 件取得します。

`GET /api/v1/cloud/environments/{environment_id}/work/poll`

`self_hosted` Environment から利用可能な work item を 1 件取得します。利用可能な work がない状態でポーリングすると、JSON の `null` を Body とした **HTTP 200 OK** が返されます。

ポーリングは work item を配信しますが、確認応答は行いません。worker は Session work を実行する前に [Work item の確認応答](/ja/cloud-agents/api/environments/work/ack) を呼び出す必要があります。

## パスパラメータ

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

## リクエストヘッダー

| ヘッダー            | 必須  | 説明                                            |
| --------------- | --- | --------------------------------------------- |
| `Authorization` | はい  | `Bearer $QODER_PAT`                           |
| `Worker-ID`     | いいえ | 安定した worker 識別子。キュー統計と ack の identity チェックに推奨 |

## クエリパラメータ

| パラメータ                   | 型       | 必須  | デフォルト | 説明                                                          |
| ----------------------- | ------- | --- | ----- | ----------------------------------------------------------- |
| `block_ms`              | integer | いいえ | -     | ロングポーリングの待機時間（ミリ秒）。1 から 999 の範囲でなければならない。非ブロッキングポーリングの場合は省略 |
| `reclaim_older_than_ms` | integer | いいえ | 5000  | 配信済みだが少なくともこのミリ秒数の間確認応答されていないキュー内アイテムを再配信する。0 以上でなければならない   |

## リクエスト例

```bash theme={null}
curl -X GET "https://api.qoder.com/api/v1/cloud/environments/env_019e64e01a137caf953ac2ac7b42ec5c/work/poll?block_ms=999" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Worker-ID: byoc-worker-01"
```

## レスポンス例: work あり

**HTTP 200 OK**

```json theme={null}
{
  "id": "work_019f3be4fd2475d9a784bf2c739e1194",
  "type": "work",
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "data": {
    "type": "session",
    "id": "sess_019f3be3fa66750bb9a1fbcde85b5fe1"
  },
  "state": "queued",
  "created_at": "2026-07-01T08:15:01Z",
  "acknowledged_at": null,
  "started_at": null,
  "latest_heartbeat_at": null,
  "stop_requested_at": null,
  "stopped_at": null,
  "metadata": {}
}
```

## レスポンス例: work なし

**HTTP 200 OK**

```json theme={null}
null
```

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

[Work item オブジェクト](/ja/cloud-agents/api/environments/work/schemas#work-item-object) を返します。利用可能なアイテムがない場合は `null` を返します。

## エラー

| HTTP | type                    | トリガー                                 |
| ---- | ----------------------- | ------------------------------------ |
| 400  | `invalid_request_error` | `block_ms` が 1 から 999 の整数でない         |
| 400  | `invalid_request_error` | `reclaim_older_than_ms` が 0 以上の整数でない |
| 400  | `invalid_request_error` | Environment が `self_hosted` でない      |
| 401  | `authentication_error`  | PAT が無効または期限切れ                       |
| 403  | `permission_error`      | この操作の権限がない                           |
| 404  | `not_found_error`       | Environment が存在しない                   |

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

## 備考

* `Worker-ID` は worker が選択するビジネス識別子であり、認証クレデンシャルではありません。
* poll と ack の両方が `Worker-ID` を指定し、値が一致しない場合、ack は 409 で失敗します。
* ロングポーリングは最大でも `block_ms` の間 1 回だけ待機します。クライアントは `null` を受け取ったらポーリングを繰り返す必要があります。

## 関連

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