RunComfy API Docs

Detailed reference for the 31 tools exposed by the RunComfy MCP server. Each maps directly to a RunComfy API endpoint.

Group	Tools
Deployment management	`list_deployments`, `get_deployment`, `create_deployment`, `update_deployment`, `delete_deployment`
Inference	`submit_request`, `get_request_status`, `get_request_result`, `cancel_request`
Advanced	`call_instance_proxy`
Model catalog	`list_models`, `get_model`, `list_model_categories`
Model inference	`run_model`, `get_model_request_status`, `get_model_request_result`, `cancel_model_request`
Training datasets	`create_dataset`, `list_datasets`, `get_dataset_status`, `delete_dataset`, `upload_dataset_file_from_url`, `upload_dataset_text_file`, `get_dataset_upload_urls`
Training jobs	`submit_training_job`, `get_training_job_status`, `get_training_job_result`, `cancel_training_job`, `resume_training_job`, `edit_training_job`
Account	`get_balance`

The first three groups back the Serverless API (ComfyUI), the next two the Model API, and the training groups the Trainer API.

Serverless and Model API requests have similarly named tools. The Serverless ones (get_request_status, get_request_result, cancel_request) always take a deployment_id; the Model API ones (get_model_request_status, and so on) take only a request_id. Mixing them up yields a 404.

Deployment management

`list_deployments`

List all Serverless API deployments in your account. Backs: GET /prod/v2/deployments

Parameter	Type	Required	Description
`ids`	string[]	No	Filter to specific deployment IDs
`include_payload`	boolean	No	Include `workflow_api_json`, `overrides`, and `object_info_url`
`include_readme`	boolean	No	Include the deployment’s README markdown

Example arguments:

{}

Example response (structuredContent):

{
  "ok": true,
  "deployments": [
    {
      "id": "a1b2c3d4-...",
      "name": "text-to-image",
      "workflow_id": "00000000-...",
      "workflow_version": "v1",
      "hardware": ["AMPERE_48"],
      "min_instances": 0,
      "max_instances": 1,
      "status": "standby",
      "is_enabled": true
    }
  ]
}

`get_deployment`

Get one deployment by ID, optionally including its full workflow graph. Backs: GET /prod/v2/deployments/{deployment_id}

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment’s UUID
`include_payload`	boolean	No	Include `workflow_api_json` and node schemas — use this to discover node IDs for `submit_request`
`include_readme`	boolean	No	Include the deployment’s README

Tip: Call with include_payload=true to see every node’s ID and input names. Use those to build the overrides object for submit_request.

Example arguments:

{
  "deployment_id": "a1b2c3d4-...",
  "include_payload": true
}

`create_deployment`

Create a new Serverless API (ComfyUI) deployment from a cloud-saved workflow. Backs: POST /prod/v2/deployments

Parameter	Type	Required	Default	Description
`name`	string	Yes	—	Human-readable name
`workflow_id`	string	Yes	—	UUID of the ComfyUI workflow
`workflow_version`	string	Yes	—	Version label (e.g., `"v1"`)
`hardware`	string	No	`"AMPERE_48"`	GPU SKU (see hardware table below)
`min_instances`	integer	No	`0`	Warm instance floor (0–30). Billable if > 0.
`max_instances`	integer	No	`1`	Concurrency ceiling (1–60)
`queue_size`	integer	No	`1`	Pending requests per instance before scaling
`keep_warm_duration_in_seconds`	integer	No	`60`	Idle timeout before scale-down

Hardware SKUs:

TURING_16  |  AMPERE_24  |  AMPERE_48  |  ADA_48_PLUS
AMPERE_80  |  ADA_80_PLUS  |  HOPPER_141

Example arguments:

{
  "name": "my-flux-deployment",
  "workflow_id": "00000000-0000-0000-0000-000000001234",
  "workflow_version": "v1",
  "hardware": "AMPERE_48",
  "min_instances": 0,
  "max_instances": 2
}

For LoRA deployments, create via the RunComfy UI (Trainer > LoRA Assets > Deploy), then use list_deployments to get the deployment_id.

`update_deployment`

Partially update a deployment. Only pass the fields you want to change. Backs: PATCH /prod/v2/deployments/{deployment_id}

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment’s UUID
`name`	string	No	New name
`workflow_version`	string	No	New version label
`hardware`	string	No	New GPU SKU
`min_instances`	integer	No	New warm floor
`max_instances`	integer	No	New concurrency ceiling
`queue_size`	integer	No	New queue threshold
`keep_warm_duration_in_seconds`	integer	No	New idle timeout
`is_enabled`	boolean	No	`false` to pause, `true` to resume

Example — pause a deployment:

{
  "deployment_id": "a1b2c3d4-...",
  "is_enabled": false
}

`delete_deployment`

Permanently delete a deployment. This cannot be undone. Backs: DELETE /prod/v2/deployments/{deployment_id}

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment’s UUID

Consider update_deployment with is_enabled=false to pause instead of deleting.

Inference

`submit_request`

Submit an async inference request to a deployment. Backs: POST /prod/v2/deployments/{deployment_id}/inference

Parameter	Type	Required	Description
`deployment_id`	string	Yes	Target deployment
`overrides`	object	No	Partial workflow graph keyed by node ID (see example below)
`workflow_api_json`	object	No	Advanced: run a different workflow inline without updating the deployment
`extra_data`	object	No	E.g., `{"api_key_comfy_org": "comfyui-..."}` for ComfyUI Core API nodes
`webhook_url`	string	No	URL for push-based status updates
`webhook_intermediate_status`	boolean	No	Fire webhooks on every status change, not just terminal
`wait_for_completion`	boolean	No	If `true`, poll until done and return the result inline
`timeout_seconds`	integer	No	Max wait (default 300) when `wait_for_completion=true`

Example — text-to-image with overrides:

{
  "deployment_id": "a1b2c3d4-...",
  "overrides": {
    "6": {
      "inputs": {
        "text": "a futuristic cityscape at sunset"
      }
    },
    "31": {
      "inputs": {
        "seed": 42
      }
    }
  }
}

File inputs — pass a public URL or Base64 data URI directly in the overrides value:

{
  "deployment_id": "a1b2c3d4-...",
  "overrides": {
    "189": {
      "inputs": {
        "image": "https://example.com/input-photo.jpg"
      }
    }
  }
}

Or using Base64:

{
  "deployment_id": "a1b2c3d4-...",
  "overrides": {
    "189": {
      "inputs": {
        "image": "data:image/jpeg;base64,/9j/4AAQ..."
      }
    }
  }
}

Use get_deployment with include_payload=true to discover the node IDs and input names for your workflow.

`get_request_status`

Poll a request’s current status. Backs: GET /prod/v2/deployments/{deployment_id}/requests/{request_id}/status

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment that owns this request
`request_id`	string	Yes	The request ID returned by `submit_request`

Status lifecycle: in_queue > in_progress > completed (or cancelled). Example response:

{
  "ok": true,
  "status": {
    "request_id": "5f1ba692-...",
    "status": "in_progress",
    "queue_position": null,
    "instance_id": "1697cb1a-..."
  }
}

`get_request_result`

Fetch the final outputs of a completed request. Backs: GET /prod/v2/deployments/{deployment_id}/requests/{request_id}/result

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment that owns this request
`request_id`	string	Yes	The request ID

Output URLs are hosted for 7 days after success. Download or copy them to your own storage for longer retention. Example response:

{
  "ok": true,
  "result": {
    "request_id": "5f1ba692-...",
    "status": "succeeded",
    "outputs": {
      "9": {
        "images": [
          {
            "url": "https://serverless-api-storage.runcomfy.net/.../ComfyUI_00001_.png",
            "filename": "ComfyUI_00001_.png"
          }
        ]
      }
    },
    "created_at": "2026-04-16T03:40:52.093Z",
    "finished_at": "2026-04-16T03:44:18.401Z"
  },
  "output_urls": [
    {
      "node_id": "9",
      "channel": "images",
      "url": "https://serverless-api-storage.runcomfy.net/.../ComfyUI_00001_.png",
      "filename": "ComfyUI_00001_.png"
    }
  ]
}

`cancel_request`

Cancel a queued or running request. Backs: POST /prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment that owns this request
`request_id`	string	Yes	The request ID

Returns cancelled if accepted, or not_cancellable if the request has already completed. Example response:

{
  "ok": true,
  "cancel": {
    "request_id": "5f1ba692-...",
    "status": "completed",
    "outcome": "cancelled"
  }
}

Advanced

`call_instance_proxy`

Call a ComfyUI backend endpoint on a live instance. Backs: POST /prod/v2/deployments/{deployment_id}/instances/{instance_id}/proxy/{comfy_backend_path}

Parameter	Type	Required	Description
`deployment_id`	string	Yes	The deployment
`instance_id`	string	Yes	The running instance (from `get_request_status` when status is `in_progress`)
`comfy_backend_path`	string	Yes	The ComfyUI backend route, e.g., `api/free`
`request_body`	object	No	JSON body to send to the ComfyUI endpoint

Example — unload models to free GPU memory:

{
  "deployment_id": "a1b2c3d4-...",
  "instance_id": "1697cb1a-...",
  "comfy_backend_path": "api/free",
  "request_body": {
    "unload_models": true,
    "free_memory": true
  }
}

Instance IDs are ephemeral — they are only valid while the instance is running. If the instance shuts down, submit a new request to get a fresh instance.

Model catalog

Discovery for the Model API — hosted models you run on demand, with no deployment. Backs the Model Catalog Endpoints.

`list_models`

Browse the hosted models run_model can run. Backs: GET /v1/models

Parameter	Type	Required	Description
`search`	string	No	Case-insensitive match on id, display name, or description, e.g. `kontext`, `upscale`, `lip sync`
`category`	string	No	Capability filter, e.g. `text-to-image`, `image-to-video`
`kind`	string	No	Execution filter: `model`, `workflow`, or `inference`
`include_schema`	boolean	No	Return each model’s full `input_schema` inline. Much larger response.
`limit`	integer	No	Page size, 1–500 (default 100)
`offset`	integer	No	Rows to skip (default 0)

category is what the model does; kind is how it runs. Filter on category unless you specifically care about the execution path. For a single model, prefer get_model over include_schema.

Example arguments:

{
  "search": "kontext",
  "limit": 20
}

Example response (structuredContent):

{
  "ok": true,
  "models": [
    {
      "model_id": "blackforestlabs/flux-1-kontext/dev/image-to-image",
      "display_name": "Flux Kontext Dev",
      "description": "Edit visuals via text with multi-layer control and style memory.",
      "publisher": "blackforestlabs",
      "categories": ["image-to-image"],
      "kind": "model",
      "model_url": "https://www.runcomfy.com/models/blackforestlabs/flux-1-kontext-dev",
      "base_price_usd": 0.06,
      "price_unit": "output",
      "inputs": ["aspect_ratio", "image_url", "prompt", "seed"],
      "required_inputs": ["prompt", "image_url"]
    }
  ],
  "total": 371,
  "limit": 20,
  "offset": 0
}

base_price_usd is a base rate per price_unit (second for duration-billed models, otherwise output); most models multiply it by inputs like resolution or duration. total is the count before paging — use it to decide whether to fetch another page.

`list_model_categories`

List the capability categories models are grouped into. Backs: GET /v1/models/categories Takes no parameters. Returns values such as text-to-image and image-to-video — pass one to list_models(category=...). Derived from the catalog, so it grows as new kinds of model are published.

`get_model`

Get one model’s full input schema before building a request. Backs: GET /v1/models/{model_id}

Parameter	Type	Required	Description
`model_id`	string	Yes	The identifier, slashes included, e.g. `blackforestlabs/flux-1-kontext/pro/edit`

input_schema is the JSON Schema for run_model’s inputs: property types, defaults, enums, and min/max ranges. Read it rather than guessing parameter names. Example response:

{
  "ok": true,
  "model": {
    "model_id": "blackforestlabs/flux-1-kontext/pro/edit",
    "display_name": "Flux Kontext Pro",
    "categories": ["image-to-image"],
    "base_price_usd": 0.044,
    "price_unit": "output",
    "input_schema": {
      "type": "object",
      "required": ["prompt", "image_url"],
      "properties": {
        "prompt": { "type": "string" },
        "image_url": { "type": "string", "format": "image_uri" },
        "aspect_ratio": {
          "type": "string",
          "default": "16:9",
          "enum": ["21:9", "16:9", "1:1", "9:16"]
        },
        "num_inference_steps": {
          "type": "integer",
          "default": 28,
          "minimum": 10,
          "maximum": 50
        }
      }
    }
  }
}

The schema describes the request body only — playground rendering hints (title, x-order, x-rc-group-id, widget-style format values) are stripped, so format appears only where a field takes a public file URL.

Model inference

`run_model`

Run a hosted model on demand — no deployment needed. Backs: POST /v1/models/{model_id}

Parameter	Type	Required	Description
`model_id`	string	Yes	The model’s identifier, slashes included
`inputs`	object	No	Request body matching the model’s Input schema (see `get_model`)
`wait_for_completion`	boolean	No	If `true`, poll until done and return the result inline
`timeout_seconds`	integer	No	Max wait (default 300) when `wait_for_completion=true`

File inputs must be publicly accessible HTTPS URLs that a plain unauthenticated GET can fetch. Unlike submit_request, the Model API does not take Base64 data URIs. Example arguments:

{
  "model_id": "blackforestlabs/flux-1-kontext/pro/edit",
  "inputs": {
    "prompt": "She is now holding an orange umbrella and smiling",
    "image_url": "https://example.com/photo.webp",
    "aspect_ratio": "16:9"
  }
}

Running a trained LoRA without deploying it — call the LoRA’s base model and pass the LoRA as an input:

{
  "model_id": "<base-model-id>",
  "inputs": {
    "prompt": "a portrait in the style",
    "lora": { "path": "my_first_lora_3000.safetensors" }
  }
}

path accepts either a name from your LoRA Assets or a public URL — including a checkpoint URL from get_training_job_result.

`get_model_request_status`

Poll a Model API request’s status. Backs: GET /v1/requests/{request_id}/status

Parameter	Type	Required	Description
`request_id`	string	Yes	The request ID returned by `run_model`

Lifecycle: in_queue → in_progress → completed / cancelled. While in_queue the payload also carries queue_position.

`get_model_request_result`

Fetch a completed Model API request’s outputs. Backs: GET /v1/requests/{request_id}/result

Parameter	Type	Required	Description
`request_id`	string	Yes	The request ID

The output shape is defined by the model’s Output schema. Any hosted asset URLs found inside it are also flattened into output_urls for convenience. Example response:

{
  "ok": true,
  "result": {
    "request_id": "5f1ba692-...",
    "status": "succeeded",
    "output": { "image": "https://playgrounds-storage-public.runcomfy.net/a.png" }
  },
  "output_urls": [
    {
      "field": "image",
      "json_path": "image",
      "url": "https://playgrounds-storage-public.runcomfy.net/a.png"
    }
  ]
}

`cancel_model_request`

Cancel a queued Model API request. Backs: POST /v1/requests/{request_id}/cancel

Parameter	Type	Required	Description
`request_id`	string	Yes	The request ID

Returns cancelled if accepted, or not_cancellable if the request is already in progress or finished.

Training datasets

Datasets for the Trainer API. Create one, upload media plus matching captions, then poll until it is READY — only READY datasets can be mounted by a training job. Backs the Dataset endpoints.

`create_dataset`

Create an empty dataset. Backs: POST /prod/v1/trainers/datasets

Parameter	Type	Required	Description
`name`	string	No	Human-readable name, unique in your account. Omit to have one generated.

The name — not the id — is what an AI Toolkit config references as /app/ai-toolkit/datasets/{dataset_name}. A new dataset starts in DRAFT.

`list_datasets`

List datasets in your account. Backs: GET /prod/v1/trainers/datasets

Parameter	Type	Required	Description
`include_raw`	boolean	No	Return each dataset’s unabridged payload instead of the compact summary

The listing carries no per-file detail — use get_dataset_status for a dataset’s files.

`get_dataset_status`

Get a dataset’s status and its successfully uploaded files. Backs: GET /prod/v1/trainers/datasets/{dataset_id}/status

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The dataset’s UUID

Lifecycle: DRAFT → UPLOADING → READY, or FAILED (which sets error). Files still uploading or that failed do not appear in files.

`delete_dataset`

Permanently delete a dataset. Backs: DELETE /prod/v1/trainers/datasets/{dataset_id}

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The dataset’s UUID

This cannot be undone.

`upload_dataset_file_from_url`

Add one file to a dataset by fetching it from a public URL. Backs: POST /prod/v1/trainers/datasets/{dataset_id}/upload

Parameter	Type	Required	Description
`dataset_id`	string	Yes	Target dataset
`source_url`	string	Yes	Publicly reachable HTTPS URL for an image, video, or `.txt` caption. Under 150 MB.
`filename`	string	No	Name to store it under. Defaults to the URL’s basename.

The MCP server runs remotely and cannot read files on your machine. A local path passed as source_url is rejected — use get_dataset_upload_urls instead.

Each image or video needs a caption .txt with the same base name: img_0001.jpg pairs with img_0001.txt. Re-uploading the same filename overwrites the previous copy.

`upload_dataset_text_file`

Write a caption straight into the dataset, with no file hosting needed. Backs: POST /prod/v1/trainers/datasets/{dataset_id}/upload

Parameter	Type	Required	Description
`dataset_id`	string	Yes	Target dataset
`filename`	string	Yes	Must share the base name of the media it captions, e.g. `img_0001.txt`
`text`	string	Yes	Caption body

Example arguments:

{
  "dataset_id": "ds_123",
  "filename": "img_0001.txt",
  "text": "a photo of a golden retriever in a park"
}

`get_dataset_upload_urls`

Get signed upload URLs for files the server cannot fetch itself. Backs: POST /prod/v1/trainers/datasets/{dataset_id}/get-upload-endpoint

Parameter	Type	Required	Description
`dataset_id`	string	Yes	Target dataset
`filename_to_byte_size`	object	Yes	Map of filename → exact size in bytes

Use this for local files and anything over 150 MB, then PUT each file’s bytes to the returned upload_url with the returned method and headers. Example arguments:

{
  "dataset_id": "ds_123",
  "filename_to_byte_size": {
    "img_0001.jpg": 2000000,
    "img_0001.txt": 12000
  }
}

The signature is derived from the byte size, so a wrong value is rejected by storage at PUT time. Signed URLs are short-lived; call again for a fresh one. After every PUT succeeds, poll get_dataset_status until READY.

Training jobs

AI Toolkit LoRA training. Backs the Training job endpoints.

`submit_training_job`

Submit an AI Toolkit training job. Backs: POST /prod/v1/trainers/ai-toolkit/jobs

Parameter	Type	Required	Description
`config_file`	string	Yes	The complete AI Toolkit YAML config, as a string
`gpu_type`	string	No	`ADA_80_PLUS` (H100, default) or `HOPPER_141` (H200)
`gpu_count`	integer	No	`1` for single-GPU (default) or `8` for multi-GPU
`gpu_id`	string	No	Specific GPU selector, e.g. `"#1"`

Multi-GPU (gpu_count: 8) is only supported on ADA_80_PLUS; the tool rejects other combinations before calling the API. Two paths in the config are fixed by the platform:

training_folder must be /app/ai-toolkit/output
the dataset’s folder_path must be /app/ai-toolkit/datasets/{dataset_name}, where dataset_name is the dataset’s name, not its id

Training runs for hours, so this tool returns as soon as the job is queued rather than waiting. Track it with get_training_job_status.

`get_training_job_status`

Poll a training job’s status and step progress. Backs: GET /prod/v1/trainers/ai-toolkit/jobs/{job_id}/status

Parameter	Type	Required	Description
`job_id`	string	Yes	The job’s UUID

Lifecycle: IN_QUEUE → RUNNING → STOPPED (finished or preempted), FAILED (with an error), or CANCELED. Example response:

{
  "ok": true,
  "status": {
    "id": "job_123",
    "status": "RUNNING",
    "progress": { "current_step": 320, "total_steps": 2000, "percent": 16 }
  }
}

`get_training_job_result`

Fetch a training job’s artifacts as hosted URLs. Backs: GET /prod/v1/trainers/ai-toolkit/jobs/{job_id}/result

Parameter	Type	Required	Description
`job_id`	string	Yes	The job’s UUID

Returns checkpoints (.safetensors), the resolved config, and sample outputs, flattened into artifact_urls. Safe to call while the job is still RUNNING — the list grows over time — and after a FAILED or CANCELED job to recover whatever was produced. Feed a checkpoint URL to run_model as {"lora": {"path": "<url>"}} to run inference on it.

`cancel_training_job`

Cancel a queued or running training job. Backs: POST /prod/v1/trainers/ai-toolkit/jobs/{job_id}/cancel

Parameter	Type	Required	Description
`job_id`	string	Yes	The job’s UUID

Progress stops, but get_training_job_result still returns any checkpoints produced so far.

`resume_training_job`

Resume a stopped job from its latest checkpoint. Backs: POST /prod/v1/trainers/ai-toolkit/jobs/{job_id}/resume

Parameter	Type	Required	Description
`job_id`	string	Yes	The job’s UUID

Reuses the same job_id rather than creating a new job, restarting from the highest-step checkpoint (or step 0 if none exists). Useful after a preemption. For a FAILED job, read error from the status first and fix the cause — often via edit_training_job — before resuming.

`edit_training_job`

Replace the config of a non-running job. Backs: POST /prod/v1/trainers/ai-toolkit/jobs/{job_id}/edit

Parameter	Type	Required	Description
`job_id`	string	Yes	The job’s UUID
`config_file`	string	Yes	The updated AI Toolkit YAML

Only works while the job is STOPPED, CANCELED, or FAILED, and config.name must still match the original job’s name. GPU type and count are chosen at resume time, so call resume_training_job afterwards to re-queue.

Account

`get_balance`

Get the account’s remaining RunComfy balance. Backs: GET /prod/v2/balance Takes no parameters. One wallet funds every product, so this is the figure Serverless deployments, run_model requests, and training jobs all draw down — and the one checked before work is allowed to start. Example response:

{
  "ok": true,
  "balance": {
    "balance_microdollars": 4830000,
    "balance_usd": 4.83,
    "currency": "USD"
  }
}

Use balance_usd for reading and balance_microdollars (millionths of a dollar) for exact arithmetic and threshold checks. A zero balance is a normal response, not an error. See Balance for minimums and what the figure covers.

​Deployment management

​list_deployments

​get_deployment

​create_deployment

​update_deployment

​delete_deployment

​Inference

​submit_request

​get_request_status

​get_request_result

​cancel_request

​Advanced

​call_instance_proxy

​Model catalog

​list_models

​list_model_categories

​get_model

​Model inference

​run_model

​get_model_request_status

​get_model_request_result

​cancel_model_request

​Training datasets

​create_dataset

​list_datasets

​get_dataset_status

​delete_dataset

​upload_dataset_file_from_url

​upload_dataset_text_file

​get_dataset_upload_urls

​Training jobs

​submit_training_job

​get_training_job_status

​get_training_job_result

​cancel_training_job

​resume_training_job

​edit_training_job

​Account

​get_balance

Deployment management

`list_deployments`

`get_deployment`

`create_deployment`

`update_deployment`

`delete_deployment`

Inference

`submit_request`

`get_request_status`

`get_request_result`

`cancel_request`

Advanced

`call_instance_proxy`

Model catalog

`list_models`

`list_model_categories`

`get_model`

Model inference

`run_model`

`get_model_request_status`

`get_model_request_result`

`cancel_model_request`

Training datasets

`create_dataset`

`list_datasets`

`get_dataset_status`

`delete_dataset`

`upload_dataset_file_from_url`

`upload_dataset_text_file`

`get_dataset_upload_urls`

Training jobs

`submit_training_job`

`get_training_job_status`

`get_training_job_result`

`cancel_training_job`

`resume_training_job`

`edit_training_job`

Account

`get_balance`