Claude Platform Docs

Work

Get Work Item
client.Beta.Environments.Work.Get(ctx, workID, params) (*BetaSelfHostedWork, error)
GET/v1/environments/{environment_id}/work/{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.

Poll for Work
client.Beta.Environments.Work.Poll(ctx, environmentID, params) (*BetaSelfHostedWork, error)
GET/v1/environments/{environment_id}/work/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.

Acknowledge Work
client.Beta.Environments.Work.Ack(ctx, workID, params) (*BetaSelfHostedWork, error)
POST/v1/environments/{environment_id}/work/{work_id}/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.

Record Heartbeat
client.Beta.Environments.Work.Heartbeat(ctx, workID, params) (*BetaSelfHostedWorkHeartbeatResponse, error)
POST/v1/environments/{environment_id}/work/{work_id}/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.

Stop Work
client.Beta.Environments.Work.Stop(ctx, workID, params) (*BetaSelfHostedWork, error)
POST/v1/environments/{environment_id}/work/{work_id}/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.

List Work Items
client.Beta.Environments.Work.List(ctx, environmentID, params) (*PageCursor[BetaSelfHostedWork], error)
GET/v1/environments/{environment_id}/work

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
client.Beta.Environments.Work.Update(ctx, workID, params) (*BetaSelfHostedWork, error)
POST/v1/environments/{environment_id}/work/{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.

Get Queue Statistics
client.Beta.Environments.Work.Stats(ctx, environmentID, query) (*BetaSelfHostedWorkQueueStats, error)
GET/v1/environments/{environment_id}/work/stats

Get statistics about the work queue for an environment.

Models
type BetaSelfHostedWork struct { Type: "work"; ID; AcknowledgedAt; /* 10 more */ }

Work resource representing a unit of work in a self-hosted environment.

Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox.

type BetaSelfHostedWorkHeartbeatResponse struct { Type: "work_heartbeat"; LastHeartbeat; LeaseExtended; /* 2 more */ }

Response after recording a heartbeat for a work item.

Type WorkHeartbeat

The type of response

defaultwork_heartbeat
LastHeartbeat string

RFC 3339 timestamp of the actual heartbeat from DB

LeaseExtended bool

Whether the heartbeat succeeded in extending the lease

State BetaSelfHostedWorkHeartbeatResponseState

Current state of the work item (active/stopping/stopped)

One of the following:
const BetaSelfHostedWorkHeartbeatResponseStateQueued BetaSelfHostedWorkHeartbeatResponseState = "queued"
const BetaSelfHostedWorkHeartbeatResponseStateStarting BetaSelfHostedWorkHeartbeatResponseState = "starting"
const BetaSelfHostedWorkHeartbeatResponseStateActive BetaSelfHostedWorkHeartbeatResponseState = "active"
const BetaSelfHostedWorkHeartbeatResponseStateStopping BetaSelfHostedWorkHeartbeatResponseState = "stopping"
const BetaSelfHostedWorkHeartbeatResponseStateStopped BetaSelfHostedWorkHeartbeatResponseState = "stopped"
TTLSeconds int64

Effective TTL applied to the lease

type BetaSelfHostedWorkListResponse struct { Data; NextPage }

Response when listing work items with cursor-based pagination.

type BetaSelfHostedWorkQueueStats struct { Type: "work_queue_stats"; Depth; OldestQueuedAt; /* 2 more */ }

Statistics about the work queue for an environment.

Uses Redis Stream consumer group metrics for O(1) queries.

Type WorkQueueStats

The type of object

defaultwork_queue_stats
Depth int64

Number of work items waiting to be picked up (lag from consumer group)

OldestQueuedAt string

RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty

Pending int64

Number of work items being processed (polled but not acknowledged)

default0
WorkersPolling int64

Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests.

type BetaSelfHostedWorkStopRequestParam struct { Force }

Request to stop a work item.

Force bool Optional

If true, immediately stop work without graceful shutdown

defaultfalse
type BetaSelfHostedWorkUpdateRequestParam struct { Metadata }

Request to update work item metadata.

Metadata map[string, string]

Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata.

type BetaSessionWorkData struct { Type: "session"; ID }

Work data for session work items.

This resource type is used when work represents a session that needs to be executed in a self-hosted environment.

Type Session

Type of work data

ID string

Session identifier (e.g., 'session_...')