Controller APIs

Warning

This page documents the behavior of LMCache’s in-process mode (deprecated). Please consider using LMCache MP mode for better feature support and performance. For the MP mode equivalent of this page, see HTTP API.

These APIs are specific to the LMCache Controller component. They provide visibility into registered instances, workers, and key statistics.

GET /controller/key-stats — Key Statistics

Get key statistics across all instances and workers.

• Method: GET

• Path: /controller/key-stats

• Parameters: None

• Response: application/json

curl http://localhost:6999/controller/key-stats

Example Response (HTTP 200):

{
  "total_key_count": 1500,
  "total_instance_count": 2,
  "total_worker_count": 4,
  "instances": [
    {
      "instance_id": "instance_001",
      "key_count": 800,
      "worker_count": 2
    },
    {
      "instance_id": "instance_002",
      "key_count": 700,
      "worker_count": 2
    }
  ]
}

Error Response (controller not available, HTTP 503):

{
  "detail": "Controller manager not available"
}

Response Schema:

Field	Type	Description
total_key_count	int	Total number of KV keys across all instances
total_instance_count	int	Total number of registered instances
total_worker_count	int	Total number of workers across all instances
instances	list	Per-instance breakdown (see below)

Instance Schema:

Field	Type	Description
instance_id	str	Unique identifier of the instance
key_count	int	Number of KV keys held by this instance
worker_count	int	Number of workers in this instance

GET /controller/workers — Worker Information

Get worker information with flexible query parameters. Behavior depends on the combination of parameters:

• No parameters: List all registered workers across all instances.

• ``instance_id`` only: List all workers for a specific instance.

• ``instance_id`` and ``worker_id``: Get detailed info about a specific worker.

• Method: GET

• Path: /controller/workers

• Parameters:

  Name	Type	Description
  instance_id	str	(Optional) Instance ID to filter workers
  worker_id	int	(Optional) Worker ID for specific worker details (requires instance_id)

• Response: application/json

# List all workers
curl http://localhost:6999/controller/workers

# List workers for a specific instance
curl "http://localhost:6999/controller/workers?instance_id=instance_001"

# Get a specific worker
curl "http://localhost:6999/controller/workers?instance_id=instance_001&worker_id=0"

Example Response (list workers):

{
  "workers": [
    {
      "instance_id": "instance_001",
      "worker_id": 0,
      "ip": "10.0.0.1",
      "port": 8000,
      "peer_init_url": "http://10.0.0.1:8000/init",
      "registration_time": 1706745600.0,
      "last_heartbeat_time": 1706745660.0,
      "key_count": 400
    },
    {
      "instance_id": "instance_001",
      "worker_id": 1,
      "ip": "10.0.0.2",
      "port": 8001,
      "peer_init_url": "http://10.0.0.2:8001/init",
      "registration_time": 1706745600.0,
      "last_heartbeat_time": 1706745660.0,
      "key_count": 400
    }
  ],
  "total_count": 2
}

Example Response (single worker):

{
  "instance_id": "instance_001",
  "worker_id": 0,
  "ip": "10.0.0.1",
  "port": 8000,
  "peer_init_url": "http://10.0.0.1:8000/init",
  "registration_time": 1706745600.0,
  "last_heartbeat_time": 1706745660.0,
  "key_count": 400
}

Error Response (worker not found, HTTP 404):

{
  "detail": "Worker (instance_001, 99) not found"
}

Error Response (instance not found, HTTP 404):

{
  "detail": "No workers found for instance unknown_instance"
}

Error Response (controller not available, HTTP 503):

{
  "detail": "Controller manager not available"
}

Worker Response Schema:

Field	Type	Description
instance_id	str	Instance this worker belongs to
worker_id	int	Worker index within the instance
ip	str	Worker IP address
port	int	Worker port number
peer_init_url	str	(Optional) Peer initialization URL
registration_time	float	Unix timestamp of worker registration
last_heartbeat_time	float	Unix timestamp of last heartbeat
key_count	int	Number of KV keys held by this worker