Skip to content
Everruns Everruns

List workers

GET
/v1/durable/workers
 
curl --request GET \
  --url https://app.everruns.com/api/v1/durable/workers

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
status
string

Filter by status

worker_group
string

Filter by worker group

Responses

Section titled “ Responses ”

200

Section titled “200 ”

List of workers

Media type application/json

Workers list response

object
data
required

Page of items returned by this query.

Array<object>

Worker response

object
accepting_tasks
required

Whether the worker is currently accepting new task assignments. Disabled briefly during drains or backpressure.

boolean
activity_types
required

Activity types this worker accepts. Tasks with other activity types skip this worker.

Array<string>
avg_task_duration_ms

Average task duration in milliseconds across recent activity.

integer | null format: int64
backpressure_reason

Human-readable reason the worker is rejecting tasks, when accepting_tasks is false.

string | null
current_load
required

Number of tasks currently executing on this worker.

integer format: int32
hostname

Hostname / pod name the worker is running on. Operator hint; not used for routing.

string | null
id
required

Opaque durable worker identifier (defaults to worker-<uuid>).

string
last_heartbeat_at
required

Timestamp of the most recent heartbeat from this worker (RFC 3339).

string format: date-time
max_concurrency
required

Maximum number of tasks the worker will run concurrently.

integer format: int32
metadata

Free-form worker-reported metadata (deployment, capabilities flag set, etc.).

object
started_at
required

Timestamp when this worker started accepting tasks (RFC 3339).

string format: date-time
status
required

Current lifecycle status (running, draining, stopped, etc.).

string
tasks_completed
required

Total tasks this worker has completed successfully.

integer format: int64
tasks_failed
required

Total tasks this worker has failed (including retries that were ultimately abandoned).

integer format: int64
version

Build version of the worker binary.

string | null
worker_group

Logical group this worker belongs to (used for routing). None for ungrouped workers.

string | null
summary
required

Workers summary stats

object
active
required

Workers in running state, accepting tasks.

integer
draining
required

Workers in draining state, finishing in-flight tasks but not accepting new ones.

integer
stopped
required

Workers in stopped state, neither running nor draining.

integer
total_capacity
required

Sum of max_concurrency across all active + draining workers.

integer
total_load
required

Total tasks currently in flight across all workers.

integer
total
required

Total number of items matching the query, across all pages.

integer
Example 
{
  "data": [
    {
      "accepting_tasks": true,
      "activity_types": [
        "agent_loop",
        "tool_call"
      ],
      "avg_task_duration_ms": 184,
      "backpressure_reason": "draining for deploy",
      "current_load": 3,
      "hostname": "worker-prod-7c8b9d-r2x4p",
      "id": "worker-7f3a9b2e-1c4d-4a5f-8b6c-9d0e1f2a3b4c",
      "last_heartbeat_at": "2026-05-27T15:30:42Z",
      "max_concurrency": 8,
      "started_at": "2026-05-27T08:00:00Z",
      "status": "running",
      "tasks_completed": 12843,
      "tasks_failed": 17,
      "version": "0.8.35",
      "worker_group": "session-agents"
    }
  ]
}

500

Section titled “500 ”

Internal server error

Media type application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

  • Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
  • Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null
href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null
method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null
operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null
rel
required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string
schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null
code

Stable, machine-readable error code (snake_case).

string | null
detail

Human-readable explanation specific to this occurrence.

string | null
instance

Request URI for this occurrence.

string | null
retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32
status
required

HTTP status code; mirrors the response status line.

integer format: int32
title
required

Short, human-readable summary of the problem (e.g. “Not Found”).

string
type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null
Example 
{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}