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

> Self-hosted work item, heartbeat, and queue statistics structures.

Work APIs are used by external workers attached to a `self_hosted` Environment. A worker polls for queued Session work, acknowledges the item it will run, keeps the lease alive with heartbeats, and stops the item when the work is complete or must be aborted.

## Work item object

Returned by list, poll, get, update metadata, acknowledge, and stop endpoints.

| Field                 | Type         | Description                                                                      |
| --------------------- | ------------ | -------------------------------------------------------------------------------- |
| `id`                  | string       | Work item ID with the `work_` prefix                                             |
| `type`                | string       | Always `"work"`                                                                  |
| `environment_id`      | string       | Environment ID with the `env_` prefix                                            |
| `data`                | object       | Work payload descriptor                                                          |
| `data.type`           | string       | Currently always `"session"`                                                     |
| `data.id`             | string       | Session ID with the `sess_` prefix                                               |
| `state`               | string       | Work item state. See [Work states](#work-states)                                 |
| `created_at`          | string       | Creation time in UTC                                                             |
| `acknowledged_at`     | string\|null | Time when a worker acknowledged the item, or `null` before ack                   |
| `started_at`          | string\|null | Time when the first heartbeat moved the item to `active`, or `null` before start |
| `latest_heartbeat_at` | string\|null | Latest heartbeat timestamp, or `null` before the first heartbeat                 |
| `stop_requested_at`   | string\|null | Time when a graceful stop was requested, or `null`                               |
| `stopped_at`          | string\|null | Time when the item reached `stopped`, or `null` while live                       |
| `metadata`            | object       | String-only metadata associated with the work item                               |

## Work states

| State      | Description                                                                   |
| ---------- | ----------------------------------------------------------------------------- |
| `queued`   | The work item is available to poll, or was delivered but not yet acknowledged |
| `starting` | A worker acknowledged the item and should begin executing it                  |
| `active`   | A worker sent a heartbeat and owns the current lease                          |
| `stopping` | A graceful stop was requested; the worker should drain and confirm stop       |
| `stopped`  | The item is no longer live and cannot be heartbeated                          |

## Work metadata

Work metadata is a string-only map. When a Session creates a work item, the Session metadata is projected into this string map. Use [Update work item metadata](/cloud-agents/api/environments/work/update-metadata) to merge changes:

* String values upsert a key.
* `null` deletes a key.
* Omitting `metadata` leaves the current metadata unchanged.

## Work heartbeat object

Returned by [Send work heartbeat](/cloud-agents/api/environments/work/heartbeat).

| Field            | Type    | Description                                 |
| ---------------- | ------- | ------------------------------------------- |
| `type`           | string  | Always `"work_heartbeat"`                   |
| `last_heartbeat` | string  | Server timestamp for the accepted heartbeat |
| `lease_extended` | boolean | Always `true` for a successful heartbeat    |
| `state`          | string  | Current work item state after the heartbeat |
| `ttl_seconds`    | integer | Current lease TTL in seconds                |

## Work queue stats object

Returned by [Get work queue stats](/cloud-agents/api/environments/work/stats).

| Field              | Type         | Description                                                                     |
| ------------------ | ------------ | ------------------------------------------------------------------------------- |
| `type`             | string       | Always `"work_queue_stats"`                                                     |
| `depth`            | integer      | Queued items currently claimable by workers                                     |
| `pending`          | integer      | Queued items delivered recently but not yet acknowledged                        |
| `oldest_queued_at` | string\|null | Creation time of the oldest queued item, or `null` when the queue is empty      |
| `workers_polling`  | integer      | Distinct `Worker-ID` values that polled this environment in the last 30 seconds |

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