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

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.

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

Cloud environment setup

Choose the container, network, and dependencies your agent runs in.