---
title: "Trigger proactive guest memory reclaim"
method: POST
path: "/resources/memory/reclaim"
---

# Trigger proactive guest memory reclaim

`POST /resources/memory/reclaim`

Requests runtime balloon inflation across reclaim-eligible guests. The same
planner used by host-pressure reclaim is applied, including protected floors
and per-VM step limits.

## Request body

- MemoryReclaimRequest
  - `reclaim_bytes` integer, required — Total bytes of guest memory to reclaim across eligible VMs.
  - `hold_for` string — How long to keep the reclaim hold active (Go duration string). Defaults to 5m when omitted.
  - `dry_run` boolean — Calculate a reclaim plan without applying balloon changes or creating a hold.
  - `reason` string — Optional operator-provided reason attached to logs and traces.

## Response `200`

Reclaim plan and applied results

- MemoryReclaimResponse
  - `requested_reclaim_bytes` integer, required
  - `planned_reclaim_bytes` integer, required
  - `applied_reclaim_bytes` integer, required
  - `hold_until` string, date-time — When the current manual reclaim hold expires.
  - `host_available_bytes` integer, required
  - `host_pressure_state` 'healthy' | 'pressure', required
  - `actions` MemoryReclaimAction[], required
    - `instance_id` string, required
    - `instance_name` string, required
    - `hypervisor` 'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz', required
    - `assigned_memory_bytes` integer, required
    - `protected_floor_bytes` integer, required
    - `previous_target_guest_memory_bytes` integer, required
    - `planned_target_guest_memory_bytes` integer, required
    - `target_guest_memory_bytes` integer, required
    - `applied_reclaim_bytes` integer, required
    - `status` string, required — Result of this VM's reclaim step.
    - `error` string — Error message when status is error or unsupported.

## Other responses

- `400` — Invalid reclaim request
- `401` — Unauthorized
- `500` — Internal server error

---

[API](https://skmtc.net/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.net/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kernel/hypeman-api/versions/b4642bb950dc/schema)