---
title: "Worker Heartbeat"
method: POST
path: "/internal/workers/heartbeat"
tags: ["internal"]
---

# Worker Heartbeat

`POST /internal/workers/heartbeat`

## Request

- Base URL: `https://api.oxlo.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.oxlo.ai/internal/workers/heartbeat`
- Auth: none declared

Receive heartbeat from worker.

**DYNAMIC REGISTRATION**: If worker_id is new, automatically register
it with the load balancer - no .env update needed!

This allows unlimited pods to connect dynamically:
- L40s pods (auto-scaled from RunPod)
- T4 pods (Azure or RunPod)
- A100 pods (for large models)

## Headers

- `X-Worker-Token` string

## Request body

- WorkerHeartbeat: Enhanced heartbeat payload for dynamic worker registration. Workers send this every 10-15 seconds to: 1. Auto-register if new (no .env update needed!) 2. Update stats (GPU utilization, VRAM, models) 3. Signal they're alive
  - `worker_id` string, required
  - `url` string, nullable
  - `tier` string, nullable
  - `gpu_type` string, nullable
  - `gpu_memory_gb` number, nullable
  - `gpu_memory_used_gb` number, nullable
  - `gpu_memory_available_gb` number, nullable
  - `gpu_utilization` number, nullable
  - `status` string
  - `cpu` number
  - `memory` number
  - `models` unknown[]
    - unknown
  - `loaded_models` string[]
  - `available_models` string[]
  - `loading_in_progress` boolean
  - `current_loading_model` string, nullable
  - `can_accept_new_model` boolean
  - `heavy_model_loaded` boolean

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/oxlo/apis/oxlo-backend.md) - [All operations](https://skmtc.dev/oxlo/apis/oxlo-backend/llms.txt) - [OpenAPI document](https://skmtc.dev/oxlo/apis/oxlo-backend/revisions/bc2ecdc94f31?raw)