Skip to main content
The Instance Proxy API lets you call ComfyUI’s native backend endpoints on a live instance. After submitting a job via the async queue, the status response will include an instance_id once the instance is active. With that ID, you can send authenticated requests through a proxy path to perform operational tasks such as unloading models or freeing GPU memory. When to use: Start proxy calls once the job status becomes in_progress (after cold start) or completed and you can read instance_id from the Status endpoint in Async Queue Endpoints: Monitoring Request Status.

​
Instance Proxy Endpoint

Base URL: https://api.runcomfy.net 
POST /prod/v2/deployments/{deployment_id}/instances/{instance_id}/proxy/{comfy_backend_path}

​
Path Parameters

  • deployment_id: string (required)
  • instance_id: string (required)
  • comfy_backend_path: string (required). The target ComfyUI backend route, e.g., api/free.

​
Using the Proxy

The proxy forwards your request to the live ComfyUI instance. You can call:
  • ComfyUI Backend endpoints (e.g., GET /object_info, POST /api/prompt)
  • ComfyUI Manager endpoints (e.g., POST /api/free)

​
Free Memory / Unload Models

You can release GPU memory or unload models via ComfyUI Manager’s native POST /api/free endpoint. This is useful between jobs in long-running sessions to ensure the next workflow starts from a clean state.

​
Request example

​
unload models only

curl --request POST \
  --url "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/instances/{instance_id}/proxy/api/free" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "unload_models": true
  }'
Meaning in ComfyUI: Unloads currently loaded model weights (checkpoints/LoRAs/CLIP/VAE) from memory; does not clear the execution cache. Equivalent in the ComfyUI web UI: Manager → Unload models. Unload models in ComfyUI

​
unload models and free memory

curl --request POST \
  --url "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/instances/{instance_id}/proxy/api/free" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "unload_models": true,
    "free_memory": true
  }'
Meaning in ComfyUI: Unloads models and clears the execution cache to return cached GPU VRAM. Equivalent in the ComfyUI web UI: Manager → Unload models and Clear execution cache (free memory). Unload models + clear execution cache in ComfyUI

​
Response example

200 OK (no response body)

​
Lifecycle Notes and Errors

  • An instance_id is valid only while its instance is running. If the instance shuts down due to keep-warm/idle timeout, subsequent proxy calls will fail. Submit a new job to start a fresh instance and obtain a new instance_id.
  • Immediately after submitting a request, proxy calls may fail until the job status shows in_progress (after cold start) or completed in the Status endpoint. Poll the status in Async Queue Endpoints: Monitoring Request Status and retry the proxy call once it transitions.