> ## 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.

# Poll work

> Claim one available work item from a self-hosted Environment.

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

Claims one available work item for a `self_hosted` Environment. Polling with no available work returns **HTTP 200 OK** with a JSON `null` body.

Polling delivers a work item but does not acknowledge it. A worker should call [Acknowledge work item](/cloud-agents/api/environments/work/ack) before executing the Session work.

## Path parameters

| Parameter        | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| `environment_id` | string | Environment ID with the `env_` prefix |

## Headers

| Header          | Required | Description                                                                 |
| --------------- | -------- | --------------------------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer $QODER_PAT`                                                         |
| `Worker-ID`     | No       | Stable worker identity. Recommended for queue stats and ack identity checks |

## Query parameters

| Parameter               | Type    | Required | Default | Description                                                                                                                  |
| ----------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `block_ms`              | integer | No       | -       | Long-poll wait time in milliseconds. Must be between 1 and 999. Omit for non-blocking poll                                   |
| `reclaim_older_than_ms` | integer | No       | 5000    | Redeliver a queued item when it was delivered but not acknowledged for at least this many milliseconds. Must be non-negative |

## Example request

```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"
```

## Example response: work available

**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": {}
}
```

## Example response: no work

**HTTP 200 OK**

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

## Response fields

Returns a [Work item object](/cloud-agents/api/environments/work/schemas#work-item-object), or `null` when no item is available.

## Errors

| HTTP | Type                    | Trigger                                               |
| ---- | ----------------------- | ----------------------------------------------------- |
| 400  | `invalid_request_error` | `block_ms` is not an integer between 1 and 999        |
| 400  | `invalid_request_error` | `reclaim_older_than_ms` is not a non-negative integer |
| 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 not found                                 |

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.

## Notes

* `Worker-ID` is a worker-chosen business identifier, not an authentication credential.
* If both poll and ack provide `Worker-ID`, ack fails with 409 when the values do not match.
* Long polling waits at most once for `block_ms`; clients should repeat polling when they receive `null`.

## Related

<CardGroup cols={2}>
  <Card title="Cloud environment setup" icon="server" href="/cloud-agents/environments">
    Choose the container, network, and dependencies your agent runs in.
  </Card>
</CardGroup>