GET /api/capacity

Read the host capacity snapshot.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/capacity

read

Read CPU, memory, VM count, and allocation totals for one Lite host.

Use your host URL and API key as shell variables:

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

cURL template

curl --request GET "${baseUrl}/api/capacity" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.

Response

Returns one JSON object.

Field	Type	Description
host_vcpus	integer	Physical CPU count on this Lite host.
host_memory_mb	integer	Physical memory in MiB.
allocatable_vcpus	integer	Configured vCPU allocation threshold after overcommit policy.
allocatable_memory_mb	integer	Configured memory allocation threshold in MiB.
running_vcpus	integer	vCPUs currently used by running VMs.
running_memory_mb	integer	Memory currently used by running VMs, in MiB.
committed_vcpus	integer	vCPUs committed by created, running, and stopped VMs. Failed VMs are excluded.
committed_memory_mb	integer	Memory committed by created, running, and stopped VMs. Failed VMs are excluded.
vm_count	integer	Number of VMs known to this host.
running_count	integer	Number of VMs in running state.

Examples

Call example

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

curl "${baseUrl}/api/capacity" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Response example

{
  "host_vcpus": 16,
  "host_memory_mb": 32768,
  "allocatable_vcpus": 16,
  "allocatable_memory_mb": 28672,
  "running_vcpus": 4,
  "running_memory_mb": 4096,
  "committed_vcpus": 6,
  "committed_memory_mb": 8192,
  "vm_count": 3,
  "running_count": 2
}

Errors

Status	Code	Description
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	API key is valid but not allowed to access the endpoint.