> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-wan3-30off-promo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud API Overview

> Programmatic access to Comfy Cloud for running workflows, managing files, and monitoring execution

<Warning>
  **Experimental API:** This API is experimental and subject to change. Endpoints, request/response formats, and behavior may be modified without notice.
</Warning>

# Comfy Cloud API

The Comfy Cloud API provides programmatic access to run workflows on Comfy Cloud infrastructure. The API is compatible with local ComfyUI's API, making it easy to migrate existing integrations.

If you are working in Python or TypeScript, use the [Comfy SDKs](/development/api-development/sdks). They wrap this API and are the shortest path to running a workflow. This page covers what is specific to Comfy Cloud: your API key, credits, and concurrency limits. Everything else is in the [Cloud API Reference](/development/cloud/api-reference).

<Note>
  **Subscription required:** API access is available on the **Standard**, **Creator** and **Pro** tiers. The Free tier does not include API access. See [pricing plans](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api) for details.
</Note>

## Credits and Usage

API requests draw from the same monthly credit allocation as the Comfy Cloud web UI. There is no separate API credit pool. Each tier's included credits, top-up options, and per-workflow runtime caps apply to API jobs in exactly the same way as UI jobs. See the [pricing page](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api) for the monthly credit amounts on the Standard, Creator and Pro tiers. If you run out of credits mid-month, top-ups can be purchased from your account dashboard.

## Base URL

```
https://cloud.comfy.org
```

This is also the SDK's default target, so you do not need to configure it for Comfy Cloud. To point the same code at a serverless deployment or your own ComfyUI, set `COMFY_BASE_URL`. See [Choosing a base URL](/development/api-development/sdks#choosing-a-base-url).

## Authentication

All API requests require an API key. Over raw HTTP you pass it in the `X-API-Key` header. With the SDKs you hand it to the client once and the client authenticates every request for you.

### Getting an API Key

See [Getting an API Key](/development/api-development/getting-an-api-key) for instructions on creating and managing your Cloud API key.

### Using the API Key

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://cloud.comfy.org/api/user" \
    -H "X-API-Key: $COMFY_CLOUD_API_KEY"
  ```

  ```python Python theme={null}
  import os
  from comfy_sdk import Comfy

  client = Comfy(api_key=os.environ["COMFY_CLOUD_API_KEY"])
  ```

  ```typescript TypeScript theme={null}
  import { Comfy } from "@comfyorg/sdk";

  const client = new Comfy({ apiKey: process.env.COMFY_CLOUD_API_KEY! });
  ```
</CodeGroup>

An invalid or missing key returns `401`, which the SDKs raise as `Unauthorized`. A key on an inactive subscription returns `429`.

The same key is used for [Partner Nodes](/tutorials/partner-nodes/overview). Over HTTP you pass it again in `extra_data.api_key_comfy_org`. The SDKs do it for you when you pass `api_key` to `submit()`.

## Running Workflows

Workflows are submitted in [API format](/development/api-development/workflow-api-format), the JSON produced by the ComfyUI frontend's "Export Workflow (API)" option. You submit a workflow, the job executes asynchronously, and you download the outputs when it finishes.

<Card title="Comfy SDKs" icon="code" href="/development/api-development/sdks">
  Install, submit a workflow, follow live progress, and save the outputs, in Python or TypeScript. Start here.
</Card>

To call the HTTP endpoints directly, from another language or for the capabilities below, see the [Cloud API Reference](/development/cloud/api-reference). It documents submission, polling, the WebSocket protocol, and output downloads with curl, Python, and TypeScript examples.

### Parallel Execution (Concurrent Jobs)

API users can submit multiple workflows concurrently without waiting for previous jobs to complete. Submission returns as soon as the job is accepted, so you can keep several in flight. The dispatcher will run them in parallel up to your subscription tier's limit.

| Subscription Tier | Concurrent Jobs |
| ----------------- | --------------- |
| Standard          | 1               |
| Creator           | 3               |
| Pro               | 5               |

Jobs submitted beyond your concurrency limit will queue normally and execute automatically as slots free up. If the queue itself is full, the SDKs retry for you within a bounded budget before raising `QueueFull`.

<Info>
  Parallel execution is currently available via the API only. See [pricing plans](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api) for subscription details.
</Info>

## What the SDKs Don't Cover Yet

The SDKs do one thing: run a workflow and get the results back. The rest of the Cloud surface is reachable over HTTP only, so call these endpoints directly even if you use an SDK for execution.

| Capability                                    | Endpoint                | Reference                                                             |
| --------------------------------------------- | ----------------------- | --------------------------------------------------------------------- |
| Queue status, running and pending jobs        | `GET /api/queue`        | [Queue Management](/development/cloud/api-reference#queue-management) |
| Interrupt the current execution               | `POST /api/interrupt`   | [Queue Management](/development/cloud/api-reference#queue-management) |
| Node definitions and input specs              | `GET /api/object_info`  | [Object Info](/development/cloud/api-reference#object-info)           |
| Browse available models                       | Model endpoints         | [Cloud API Reference](/development/cloud/api-reference)               |
| Account and user information                  | `GET /api/user`         | [Cloud API Reference](/development/cloud/api-reference)               |
| Mask uploads that reference an existing image | `POST /api/upload/mask` | [Uploading Inputs](/development/cloud/api-reference#uploading-inputs) |

Canceling a job is covered by both: the SDKs cancel a job you hold a handle to, and `POST /api/queue` cancels by ID.

## Available Endpoints

| Category                                                                       | Description                            |
| ------------------------------------------------------------------------------ | -------------------------------------- |
| [Workflows](/development/cloud/api-reference#running-workflows)                | Submit workflows, check status         |
| [Jobs](/development/cloud/api-reference#checking-job-status)                   | Monitor job status and queue           |
| [Inputs](/development/cloud/api-reference#uploading-inputs)                    | Upload images, masks, and other inputs |
| [Outputs](/development/cloud/api-reference#downloading-outputs)                | Download generated content             |
| [WebSocket](/development/cloud/api-reference#websocket-for-real-time-progress) | Real-time progress updates             |
| [Object Info](/development/cloud/api-reference#object-info)                    | Available nodes and their definitions  |

## Error Handling

REST endpoints return standard HTTP status codes:

| Status | Description                                    |
| ------ | ---------------------------------------------- |
| `400`  | Invalid request (bad workflow, missing fields) |
| `401`  | Unauthorized (invalid or missing API key)      |
| `402`  | Insufficient credits                           |
| `429`  | Subscription inactive                          |
| `500`  | Internal server error                          |

The SDKs raise these as typed exceptions instead, including `Unauthorized`, `InvalidWorkflow`, `InsufficientCredits`, `QueueFull`, and `JobFailed`, all extending `ComfyError`.

Execution failures are separate from HTTP errors. See [Error Handling](/development/cloud/api-reference#error-handling) for the `exception_type` values delivered during execution.

## Next Steps

<CardGroup cols={2}>
  <Card title="Comfy SDKs" icon="code" href="/development/api-development/sdks">
    Run workflows from Python or TypeScript. Assets, live events, and typed errors.
  </Card>

  <Card title="Cloud API Reference" icon="book" href="/development/cloud/api-reference">
    Complete endpoint documentation with curl, Python, and TypeScript examples.
  </Card>

  <Card title="Comfy API v2 Reference" icon="cloud" href="/api-reference/v2/overview">
    The versioned HTTP API underneath both SDKs. Use it from any language.
  </Card>

  <Card title="OpenAPI Specification" icon="file-code" href="/development/cloud/openapi">
    Machine-readable API spec for code generation.
  </Card>
</CardGroup>