Skip to main content
Worker endpoints allow you to monitor the health and status of distributed worker nodes in the Amp cluster. Workers are responsible for executing extraction jobs.

​
List Workers

Retrieves a list of all registered workers with their basic information.

​
Response

​
workers
array
required
List of all registered workers

​
Example Request

curl http://localhost:1610/workers

​
Example Response

{
  "workers": [
    {
      "node_id": "worker-01h2xcejqtf2nbrexx3vqjhp41",
      "heartbeat_at": "2025-01-15T17:20:15.456789Z"
    },
    {
      "node_id": "indexer-node-1",
      "heartbeat_at": "2025-01-15T17:20:10.123456Z"
    }
  ]
}

​
Get Worker Details

Retrieves detailed information for a specific worker by its node ID, including version and build metadata.

​
Path Parameters

​
id
string
required
The unique node identifier of the worker to retrieve

​
Response

​
node_id
string
required
Unique identifier for the worker node
​
created_at
string
required
Timestamp when the worker was first created in the system (RFC3339 format). This timestamp never changes and represents when the worker first appeared in the system.
​
registered_at
string
required
Timestamp when the worker last registered (RFC3339 format). Updated each time a worker re-registers with the system. Use this to track worker restarts.
​
heartbeat_at
string
required
Last heartbeat timestamp (RFC3339 format). The most recent time this worker sent a heartbeat signal.
​
info
object
required
Worker metadata including version and build information

​
Example Request

curl http://localhost:1610/workers/worker-01h2xcejqtf2nbrexx3vqjhp41

​
Example Response

{
  "node_id": "worker-01h2xcejqtf2nbrexx3vqjhp41",
  "created_at": "2025-01-15T14:30:00.123456Z",
  "registered_at": "2025-01-15T16:45:30.789012Z",
  "heartbeat_at": "2025-01-15T17:20:15.456789Z",
  "info": {
    "version": "v0.0.22-15-g8b065bde",
    "commit_sha": "8b065bde9c1a2f3e4d5c6b7a8e9f0a1b2c3d4e5f",
    "commit_timestamp": "2025-01-15T14:30:00Z",
    "build_date": "2025-01-15T15:45:30Z"
  }
}

​
Response Codes

  • 200 OK - Worker information retrieved successfully
  • 400 Bad Request - Invalid node ID format
  • 404 Not Found - Worker not found
  • 500 Internal Server Error - Database error

​
Worker Health Monitoring

​
Heartbeat Tracking

Workers send periodic heartbeats to indicate they are alive and processing work. The heartbeat_at field shows the last heartbeat timestamp. Monitoring stale workers: 
# Get all workers
curl http://localhost:1610/workers

# Check heartbeat timestamps
# If heartbeat_at is significantly older than current time,
# the worker may be down or unreachable

​
Version Tracking

The detailed worker endpoint provides comprehensive build and version information:
  • version - Git describe output showing exact version
  • commit_sha - Full commit hash for source correlation
  • commit_timestamp - When the code was committed
  • build_date - When the binary was built
Use version information to ensure all workers are running compatible versions and to troubleshoot version-specific issues.

​
Worker Lifecycle

Understand worker lifecycle through timestamps:
  1. created_at - When the worker first appeared (never changes)
  2. registered_at - Last registration (updates on restart)
  3. heartbeat_at - Most recent heartbeat (updates frequently)
Detecting restarts: 
# If registered_at is recent but created_at is old,
# the worker recently restarted

​
Worker ID Format

Worker node IDs must follow these rules:
  • Start with a letter (a-z, A-Z)
  • Contain only letters, digits (0-9), underscores (_), hyphens (-), and dots (.)
  • Examples: worker-01, indexer-node-1, amp_worker.prod
Worker IDs are persistent identifiers used for job assignment and tracking. Ensure workers use consistent IDs across restarts.

Build docs developers (and LLMs) love

Get started for freeTalk to us