> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Worker Heartbeat

> Receive heartbeat from a worker.

OPTIMIZATION: Uses Redis for scalable heartbeat storage instead of database.
Database writes are expensive and heartbeats happen every 30s per worker.

Workers should call this endpoint periodically (e.g., every 30 seconds) to:
- Confirm they're still alive
- Update their status (active, idle, busy)
- Report tasks processed
- Update metadata



## OpenAPI

````yaml https://control-plane.kubiya.ai/api/openapi.json post /api/v1/workers/heartbeat
openapi: 3.1.0
info:
  title: Agent Control Plane API
  description: Multi-tenant agent orchestration with Temporal workflows
  version: 1.0.0
servers: []
security:
  - BearerAuth: []
tags:
  - name: health
    description: 🏥 **Health & Status** - Check API health and availability
  - name: authentication
    description: 🔐 **Authentication** - Token validation and auth management
  - name: agents
    description: 🤖 **Agents** - Create and manage AI agents with custom capabilities
  - name: skills
    description: 🛠️ **Tool Sets** - Manage agent skills and tool configurations
  - name: integrations
    description: 🔌 **Integrations** - Connect to external services (Kubiya managed)
  - name: custom-integrations
    description: >-
      ⚙️ **Custom Integrations** - User-defined integration instances with env
      vars, secrets, and files
  - name: integration-templates
    description: >-
      📦 **Integration Templates** - Pre-configured templates for common
      services (PostgreSQL, Redis, MongoDB, etc.)
  - name: secrets
    description: 🔑 **Secrets** - Secure credential storage and retrieval
  - name: teams
    description: 👥 **Teams** - Team management and collaboration
  - name: workflows
    description: 📊 **Workflows** - Multi-step automation and orchestration
  - name: executions
    description: ▶️ **Executions** - Track and monitor workflow runs
  - name: jobs
    description: ⏰ **Jobs** - Scheduled and webhook-triggered tasks
  - name: policies
    description: 🛡️ **Policies** - Access control and security policies
  - name: analytics
    description: 📈 **Analytics** - Usage metrics and performance monitoring
  - name: projects
    description: 📁 **Projects** - Project organization and management
  - name: environments
    description: 🌍 **Environments** - Environment configuration (dev, staging, prod)
  - name: models
    description: 🧠 **Models** - LLM model configuration and management
  - name: runtimes
    description: ⚡ **Runtimes** - Agent execution runtime environments
  - name: workers
    description: 👷 **Workers** - Worker registration and heartbeat monitoring
  - name: storage
    description: 💾 **Storage** - File storage and cloud integration
  - name: context-graph
    description: 🕸️ **Context Graph** - Knowledge graph and context management
  - name: temporal-workflows
    description: >-
      ⚙️ **Temporal Workflows** - Background workflows for context graph
      ingestion, connector operations, and scheduled jobs
  - name: templates
    description: 📝 **Templates** - Reusable configuration templates
paths:
  /api/v1/workers/heartbeat:
    post:
      summary: Worker Heartbeat
      description: >-
        Receive heartbeat from a worker.


        OPTIMIZATION: Uses Redis for scalable heartbeat storage instead of
        database.

        Database writes are expensive and heartbeats happen every 30s per
        worker.


        Workers should call this endpoint periodically (e.g., every 30 seconds)
        to:

        - Confirm they're still alive

        - Update their status (active, idle, busy)

        - Report tasks processed

        - Update metadata
      operationId: worker_heartbeat_api_v1_workers_heartbeat_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkerHeartbeatRequest'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WorkerHeartbeatRequest:
      properties:
        worker_id:
          type: string
          title: Worker Id
        environment_name:
          type: string
          title: Environment Name
        status:
          type: string
          title: Status
          default: active
        tasks_processed:
          type: integer
          title: Tasks Processed
          default: 0
        current_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Task Id
        worker_metadata:
          additionalProperties: true
          type: object
          title: Worker Metadata
          default: {}
      type: object
      required:
        - worker_id
        - environment_name
      title: WorkerHeartbeatRequest
      description: Worker heartbeat request
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your Kubiya API token (format: Bearer <token>)'

````