ComfyUI API /history Empty? Why and the Fix

I run ComfyUI on a GPU box at home (I call it La Bestia) and hit it over the API from n8n and Python scripts: blog heroes, lip-sync video, LoRA test grids. The first poller I wrote treated {}as “not done yet” and waited. That's right most of the time, which is exactly why it's dangerous: the other times, it waits forever.

Here's what's going on in the server. When you POST /prompt, ComfyUI validates the graph, gives you a prompt_id and puts the job on an in-memory queue. Nothing goes into history at that point. Only when the executor is done with the job does task_done write history[prompt_id], with the prompt, the outputs and a status. Until that moment, there is no key to return.

Rule of thumb: an empty history is only “still running” if the queue agrees.

No, and this is the one that cost me the most time. History is a plain Python dict on the prompt queue. Restart ComfyUI (a crash, an out-of-memory kill, a custom node update, Windows deciding to reboot) and it starts empty. Files already in output/ survive on disk, but the mapping from your prompt_id to those filenames is gone.

I found this on a lip-sync video job. The model loaded, VRAM spiked, ComfyUI went down and came back on its own, and my poller kept getting {}for a job that no longer existed anywhere. It sat there until the timeout, and the n8n run logged “queued OK” because that's the last thing it had actually confirmed. Since then my rule is to verify the output file, never the fact that a prompt was queued.

The same applies to eviction. ComfyUI caps history at 10,000 entries and drops the oldest first. You won't hit that on a hobby box, but a shared server running batch jobs all week can. If anything downstream needs to find a file later, store the filename in your own database the moment the job completes.

GET /queue returns two arrays, queue_running and queue_pending. Each item is a list whose second element is the prompt_id. So the loop is: ask history, and if it's empty, ask the queue. If neither has heard of your job, stop waiting. This is the poller I use now, trimmed down:

import time, requests

BASE = "http://127.0.0.1:8188"

def submit(graph: dict) -> str:
    r = requests.post(f"{BASE}/prompt", json={"prompt": graph})
    body = r.json()
    if r.status_code != 200:
        # Rejected at validation: no prompt_id, nothing will ever reach history
        raise RuntimeError(f"{body.get('error')} {body.get('node_errors')}")
    return body["prompt_id"]

def in_queue(pid: str) -> bool:
    q = requests.get(f"{BASE}/queue").json()
    return any(item[1] == pid
               for item in q["queue_running"] + q["queue_pending"])

def wait(pid: str, timeout: float = 900) -> dict:
    delay, deadline = 0.5, time.time() + timeout
    while time.time() < deadline:
        h = requests.get(f"{BASE}/history/{pid}").json()
        if pid in h:
            return h[pid]
        if not in_queue(pid):
            # Re-check history once: the job may have finished between calls
            h = requests.get(f"{BASE}/history/{pid}").json()
            if pid in h:
                return h[pid]
            raise RuntimeError("job lost (restart or eviction), resubmit")
        time.sleep(delay)
        delay = min(delay * 1.5, 5)
    raise TimeoutError(pid)

Two details matter. First, the second history check: a job can finish in the gap between your history call and your queue call, and without it you'd report a successful job as lost. Second, the backoff. Hammering /historyten times a second while a model is loading doesn't make it faster; starting at half a second and capping at five is plenty for image jobs. Video jobs get a longer timeout, not a faster loop.

Once the entry exists, don't jump straight to outputs. Read status first. It has three fields: status_str ("success" or "error"), completed, and messages. A failed job still gets a history entry, and its execution_error message tells you the node, the exception type and the message. A CUDA out-of-memory shows up right there. Checking only whether outputs is non-empty hides every one of those.

If the status is success and outputs is still empty or missing your image, it's one of these:

• No output node on that branch. Outputs only list nodes that report UI output: SaveImage, PreviewImage, a video combine node. A graph that ends in a VAE decode and nothing else runs fine and reports nothing.
• You grabbed a preview. PreviewImage results come back with type: "temp". They're real, but they live in the temp folder and get cleaned up. Use SaveImage for anything you keep.
• The whole graph was cached. Queue the exact same graph twice and ComfyUI serves every node from cache. History reports the file from the earlier run and no new image is written. If you expected a fresh render, change the seed.
• You exported the wrong JSON.The API wants the “Export (API)” format, keyed by node ID with class_type and inputs. The regular UI workflow file is a different shape and fails validation, which puts you back in the “never accepted” row.

I covered more of the workflow-hygiene side in my ComfyUI best practices post. The short version here: status_str first, outputs second, the file last.

Each output entry gives you filename, subfolder and type. Pass all three to GET /view and you get the bytes back. Then check that you actually got bytes:

def fetch_outputs(entry: dict) -> list[bytes]:
    st = entry.get("status") or {}
    if st.get("status_str") != "success":
        errs = [m for m in st.get("messages", []) if m[0] == "execution_error"]
        raise RuntimeError(errs or st)
    files = []
    for node_out in entry["outputs"].values():
        for key in ("images", "gifs", "videos"):
            for f in node_out.get(key, []):
                r = requests.get(f"{BASE}/view", params={
                    "filename": f["filename"],
                    "subfolder": f.get("subfolder", ""),
                    "type": f.get("type", "output")})
                r.raise_for_status()
                if len(r.content) < 1024:
                    raise RuntimeError(f"suspiciously small file {f['filename']}")
                files.append(r.content)
    if not files:
        raise RuntimeError("success but no files: add a SaveImage node")
    return files

The size check looks paranoid. It isn't. When ComfyUI sits behind a Cloudflare tunnel, a request without a browser-like User-Agentcan get a 403 HTML page instead of your PNG, and a script that only checks for “response came back” will happily save the error page as hero.png. I tunnel services the same way I described for n8n webhooks behind Cloudflare Access, and the fix is the same: send real headers, and validate what you received.

The websocket at /ws?clientId=<uuid> is the more precise signal. Send the same client_id in your POST /prompt body and you get executing events per node, execution_cached, execution_error and execution_success for your prompt. An executing event with node: null for your prompt_id also means it's done. ComfyUI ships a websocket example script in the repo that's worth reading.

My take: use the websocket for anything a person is watching, and polling for batch jobs. For a UI with a progress bar, the socket is clearly better. For a batch job that fires from n8n and might outlive a network blip or a ComfyUI restart, the socket adds reconnect logic and still doesn't tell you anything the queue check doesn't. A dropped socket looks exactly like a slow job. Either way, the last step is the same: fetch the file and check it.

One more thing for n8n users. If a retry fires while the first attempt is still rendering, you get two renders and two files. The idempotency patterns from my post on n8n duplicate executions apply directly: key the job on your own request ID, store the prompt_id against it, and check the queue before you resubmit.

1. Read the POST /prompt status code. 400 means rejected. Log node_errors and stop.
2. Poll history with backoff. Empty is normal for a while.
3. When history is empty, ask /queue. In the queue means wait. In neither means the job is lost, so resubmit.
4. Read status_str. On error, surface the execution_errormessage, not a generic “failed”.
5. Fetch every file via /view and check its size.Then store the filename yourself, because history won't keep it for you.

The endpoints themselves are documented in the official ComfyUI server routes reference. What the docs don't spell out is that {}is four different answers. Once your code treats it that way, the “my job vanished” bugs mostly go away.