work_items

Creates, updates, deletes, gets or lists a work_items resource.

Overview

Name	work_items
Type	Resource
Id	anthropic.environments.work_items

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Work identifier (e.g., 'work_...')
environment_id	string	Environment identifier this work belongs to (e.g., `env_...`)
acknowledged_at	string	RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox
created_at	string	RFC 3339 timestamp when work was created
▶data	object	The actual work to be performed
latest_heartbeat_at	string	RFC 3339 timestamp of the most recent heartbeat
metadata	object	User-provided metadata key-value pairs associated with this work item
started_at	string	RFC 3339 timestamp when work execution started
state	string	Current state of the work item (queued, starting, active, stopping, stopped)
stop_requested_at	string	RFC 3339 timestamp when stop was requested
stopped_at	string	RFC 3339 timestamp when work execution stopped
type	string	The type of object (always 'work') (work)

list

Name	Datatype	Description
id	string	Work identifier (e.g., 'work_...')
environment_id	string	Environment identifier this work belongs to (e.g., `env_...`)
acknowledged_at	string	RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox
created_at	string	RFC 3339 timestamp when work was created
▶data	object	The actual work to be performed
latest_heartbeat_at	string	RFC 3339 timestamp of the most recent heartbeat
metadata	object	User-provided metadata key-value pairs associated with this work item
started_at	string	RFC 3339 timestamp when work execution started
state	string	Current state of the work item (queued, starting, active, stopping, stopped)
stop_requested_at	string	RFC 3339 timestamp when stop was requested
stopped_at	string	RFC 3339 timestamp when work execution stopped
type	string	The type of object (always 'work') (work)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	environment_id, work_id		Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Retrieve detailed information about a specific work item.
list	select	environment_id		Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. List work items in an environment.
update	update	environment_id, work_id, metadata		Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Update work item metadata with merge semantics.
poll	exec	environment_id	block_ms, reclaim_older_than_ms	Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Long poll for work items in the queue.
ack	exec	environment_id, work_id		Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue.
heartbeat	exec	environment_id, work_id	desired_ttl_seconds, expected_last_heartbeat	Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Record a heartbeat for a work item to maintain the lease.
stop	exec	environment_id, work_id		Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Stop a work item, initiating graceful or forced shutdown.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
environment_id	string	(example: env_011CZkZ9X2dpNyB7HsEFoRfW)
work_id	string
block_ms	integer	How long to wait for work to arrive before returning. Must be 1-999 in milliseconds. Defaults to non-blocking (returns immediately if no work is available).
desired_ttl_seconds	integer	Desired TTL in seconds
expected_last_heartbeat	string	Expected last_heartbeat for conditional update (optimistic concurrency). Use literal 'NO_HEARTBEAT' to claim an unclaimed lease (first heartbeat). For subsequent heartbeats, echo the server's previous last_heartbeat value exactly. Returns 412 Precondition Failed if the actual value doesn't match.
reclaim_older_than_ms	integer	Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms).

SELECT examples

get

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Retrieve detailed information about a specific work item.

SELECT
id,
environment_id,
acknowledged_at,
created_at,
data,
latest_heartbeat_at,
metadata,
started_at,
state,
stop_requested_at,
stopped_at,
type
FROM anthropic.environments.work_items
WHERE environment_id = '{{ environment_id }}' -- required
AND work_id = '{{ work_id }}' -- required
;

list

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

List work items in an environment.

SELECT
id,
environment_id,
acknowledged_at,
created_at,
data,
latest_heartbeat_at,
metadata,
started_at,
state,
stop_requested_at,
stopped_at,
type
FROM anthropic.environments.work_items
WHERE environment_id = '{{ environment_id }}' -- required
;

UPDATE examples

update

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Update work item metadata with merge semantics.

UPDATE anthropic.environments.work_items
SET 
metadata = '{{ metadata }}'
WHERE 
environment_id = '{{ environment_id }}' --required
WHERE work_id = '{{ work_id }}' --required
AND metadata = '{{ metadata }}' --required
RETURNING
id,
environment_id,
acknowledged_at,
created_at,
data,
latest_heartbeat_at,
metadata,
started_at,
state,
stop_requested_at,
stopped_at,
type;

Lifecycle Methods

poll

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Long poll for work items in the queue.

EXEC anthropic.environments.work_items.poll 
@environment_id='{{ environment_id }}' --required, 
@block_ms='{{ block_ms }}', 
@reclaim_older_than_ms='{{ reclaim_older_than_ms }}'
;

ack

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue.

EXEC anthropic.environments.work_items.ack 
@environment_id='{{ environment_id }}' --required, 
@work_id='{{ work_id }}' --required
;

heartbeat

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Record a heartbeat for a work item to maintain the lease.

EXEC anthropic.environments.work_items.heartbeat 
@environment_id='{{ environment_id }}' --required, 
@work_id='{{ work_id }}' --required, 
@desired_ttl_seconds='{{ desired_ttl_seconds }}', 
@expected_last_heartbeat='{{ expected_last_heartbeat }}'
;

stop

Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly.

Stop a work item, initiating graceful or forced shutdown.

EXEC anthropic.environments.work_items.stop 
@environment_id='{{ environment_id }}' --required, 
@work_id='{{ work_id }}' --required
@@json=
'{
"force": {{ force }}
}'
;