> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runcomfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Queue Endpoints

These endpoints run **asynchronous inference jobs** against a **Serverless API (ComfyUI) Deployment**.

The pattern is always the same:

1. **Submit** a job → get a `request_id` immediately
2. **Poll status** (or use webhooks) until the run completes
3. **Fetch results** (hosted URLs) or handle failures
4. Optionally **cancel** a queued/running job

> Tip: The Serverless API (LoRA) uses the same request-id pattern—only the request schema differs. See **[Serverless API (LoRA)](/serverless-lora/introduction)**.

**Base URL**: `https://api.runcomfy.net`

***

## Queue endpoints

| Endpoint                                                            | Method | Description              |
| ------------------------------------------------------------------- | :----: | ------------------------ |
| `/prod/v2/deployments/{deployment_id}/inference`                    | `POST` | Submit a request         |
| `/prod/v2/deployments/{deployment_id}/requests/{request_id}/status` |  `GET` | Check request status     |
| `/prod/v2/deployments/{deployment_id}/requests/{request_id}/result` |  `GET` | Retrieve request results |
| `/prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel` | `POST` | Cancel a queued request  |

## Common path parameters

* `deployment_id` (string, required): The deployment you want to call.
* `request_id` (string, required for status/result/cancel): Returned by the submit call.

***

## Submit a request

```text theme={null}
POST /prod/v2/deployments/{deployment_id}/inference
```

You can submit requests in two ways:

* **Use the deployment’s cloud-saved workflow** (most common): send an `overrides` object to change only specific node inputs.
* **Send a full workflow at request time** (advanced): include `workflow_api_json` inline to run a different workflow without updating the deployment.

***

### Use cloud-saved workflow

When a workflow is deployed, RunComfy stores its `workflow_api.json`. At request time, you usually send only:

* `overrides`: a partial object keyed by node ID (as strings)
* optional webhook fields (`webhook`, `webhook_intermediate_status`)

#### What overrides reference

Overrides must match the deployed `workflow_api.json`:

* node IDs must exist
* input keys must exist under the node’s `inputs`
* values should match each node’s schema (see `object_info.json`)

See: **[Workflow Files](/serverless/workflow-files)**

For example, in `workflow_api.json`, node `"6"` is a `CLIPTextEncode` node that has a `text` input:

```json theme={null}
{
  "6": {
    "inputs": {
      "text": "Add ASCII style text only the single word \"Kontext\" no additional letters to the display",
      "speak_and_recognation": {
        "__value__": [
          false,
          true
        ]
      },
      "clip": [
        "38",
        0
      ]
    },
    "class_type": "CLIPTextEncode",
    "_meta": {
      "title": "CLIP Text Encode (Positive Prompt)"
    }
  },
  "31": {
    "inputs": {
      "seed": 736220757721744,
      "steps": 20,
      "cfg": 1,
      "sampler_name": "euler",
      "scheduler": "simple",
      "denoise": 1,
      "model": [
        "37",
        0
      ],
      "positive": [
        "35",
        0
      ],
      "negative": [
        "135",
        0
      ],
      "latent_image": [
        "124",
        0
      ]
    },
    "class_type": "KSampler",
    "_meta": {
      "title": "KSampler"
    }
  }
}
```

A matching override updates that node’s inputs:

```json theme={null}
{
  "overrides": {
    "6": {
      "inputs": {
        "text": "futuristic cityscape"
      }
    },
    "31": {
      "inputs": {
        "seed": 987654321
      }
    }
  }
}
```

Anything you omit keeps the default from the stored `workflow_api.json`.

***

### Request example (basic)

```bash theme={null}
curl --request POST \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/inference \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "overrides": {
      "31": {
        "inputs": {
          "seed": 987654321
        }
      },
      "6": {
        "inputs": {
          "text": "futuristic cityscape"
        }
      }
    }
  }'
```

***

### Request example (image/video via URL)

Use a **publicly accessible HTTPS URL** that returns the raw file via an unauthenticated `GET` request (no cookies, no login pages). Avoid expiring links.

```bash theme={null}
curl --request POST \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/inference \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "overrides": {
      "189": {
        "inputs": {
          "image": "https://example.com/new-image.jpg"
        }
      }
    }
  }'
```

***

### Request example (image/video via Base64)

```bash theme={null}
curl --request POST \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/inference \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "overrides": {
      "189": {
        "inputs": {
          "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..."
        }
      }
    }
  }'
```

***

### Request example (API nodes)

If your workflow uses ComfyUI Core API nodes (for example, nodes that require a [Comfy API key](https://platform.comfy.org/profile/api-keys)), include your Comfy Org API key(always starts with 'comfyui-') in the request body:

```bash theme={null}
curl --request POST \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/inference \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "overrides": {
      "10": {
        "inputs": {
          "prompt": "a golden retriever playing in a park"
        }
      }
    },
    "extra_data": {
      "api_key_comfy_org": "<comfy_org_api_key> starts with comfyui-xxxxx"
    }
  }'
```

***

### Response example

```json theme={null}
{
  "request_id": "{request_id}",
  "status_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/status",
  "result_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/result",
  "cancel_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel"
}
```

Successful requests return **200 OK** with:

* `request_id`: unique identifier for your job
* `status_url`: poll this to track progress
* `result_url`: fetch final outputs
* `cancel_url`: cancel if still cancellable

***

## Send dynamic workflow (or any workflow\_api.json)

Use this when you want to run a different workflow *without* changing the deployment’s stored workflow.

In this mode:

* include `workflow_api_json` in the request body
* omit `overrides` (or keep it empty)
* the job runs the workflow you sent

```bash theme={null}
curl --request POST \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/inference \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --data '{
    "workflow_api_json": {your-full-workflow-api-json-here}
  }'
```

### Response example (dynamic workflow)

```json theme={null}
{
  "request_id": "{request_id}",
  "status_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/status",
  "result_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/result",
  "cancel_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel"
}
```

***

## Monitor request status

```text theme={null}
GET /prod/v2/deployments/{deployment_id}/requests/{request_id}/status
```

Use this endpoint to poll queue progress and determine when results are ready. A typical lifecycle is `in_queue` → `in_progress` → `completed` (or `cancelled`).

### Request example

```bash theme={null}
curl --request GET \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/status \
  --header "Authorization: Bearer <token>"
```

### Response example

```json theme={null}
{
  "request_id": "{request_id}",
  "status": "in_queue",
  "queue_position": 0,
  "result_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/result",
  "status_url": "https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/status",
  "instance_id": "{instance_id}"
}
```

Fields you may see:

* `status`: `in_queue`, `in_progress`, `completed`, or `cancelled`
* `queue_position`: present while `in_queue`
* `instance_id`: present once an instance is running your job (useful for the instance proxy)

> Want to call ComfyUI backend endpoints on the live instance? See **[Instance Proxy Endpoints](/serverless/instance-proxy-endpoints)**.

***

## Retrieve request results

```text theme={null}
GET /prod/v2/deployments/{deployment_id}/requests/{request_id}/result
```

When the request completes successfully, this endpoint returns the final `outputs`.

Generated assets (images/videos) are hosted on temporary storage for convenience. Hosted output URLs remain available for up to **7 days** after success; after that, they are automatically removed. If you need longer retention, download outputs or copy them into your own storage.

If you need the *opposite* — no lingering retention at all, e.g. because your pipeline streams user-generated content — call the [delete endpoint](#delete-a-request) as soon as you have finished reading the result. It purges both the stored input assets and the generated outputs from serverless storage immediately.

### Request example

```bash theme={null}
curl --request GET \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/result \
  --header "Authorization: Bearer <token>"
```

### Response example

```json theme={null}
{
  "request_id": "{request_id}",
  "status": "succeeded",
  "outputs": {
    "136": {
      "images": [
        {
          "url": "https://example.com/ComfyUI_00001_.png",
          "filename": "ComfyUI_00001_.png",
          "subfolder": "",
          "type": "output"
        }
      ]
    }
  },
  "created_at": "2025-07-22T13:05:16.143086",
  "finished_at": "2025-07-22T13:13:03.624471",
  "instance_id": "{instance_id}"
}
```

Result payload notes:

* For `succeeded`, `outputs` contains node outputs (usually hosted URLs)
* For `failed`, you’ll receive an `error` object describing why the run failed
* For `cancelled`, `finished_at` indicates when it was cancelled

***

## Cancel a request

```text theme={null}
POST /prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel
```

Use this endpoint to cancel a queued or running job.

### Request example

```bash theme={null}
curl --request POST \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel \
  --header "Authorization: Bearer <token>"
```

### Response example

```json theme={null}
{
  "request_id": "{request_id}",
  "status": "completed",
  "outcome": "cancelled"
}
```

Successful requests return a **202 Accepted** status with a JSON object containing the cancellation outcome.

* `outcome` (string): `cancelled` if accepted; `not_cancellable` if the job is completed or otherwise cannot be cancelled.

***

## Delete a request

```text theme={null}
DELETE /prod/v2/deployments/{deployment_id}/requests/{request_id}
```

Purges every input and output asset for a request from serverless storage, bypassing the default 7-day retention window. Useful when you do not want user-uploaded content or generated outputs to sit on our side any longer than strictly necessary — for example after you have already streamed the result back to an end user.

The request must be in a **terminal state** (`succeeded`, `failed`, or `cancelled`). If the job is still running, cancel it first via the [cancel endpoint](#cancel-a-request), then delete.

### Request example

```bash theme={null}
curl --request DELETE \
  --url https://api.runcomfy.net/prod/v2/deployments/{deployment_id}/requests/{request_id} \
  --header "Authorization: Bearer <token>"
```

### Response example

```json theme={null}
{
  "request_id": "{request_id}",
  "status": "deleted",
  "deleted_objects": 3
}
```

* `deleted_objects` (integer): number of storage objects actually removed. Zero is valid — it just means there was nothing left to delete (e.g. the call was repeated).

If the request is still in progress, the call fails with **409 Conflict**.

***

## Webhooks (recommended for production)

Webhooks reduce polling and give you automatic updates. See **[Webhooks](/serverless/webhooks)**.