Skip to main content
GET
Read the queue state of one submitted request.

Authorizations

Authorization
string
header
required

Bearer token authentication. Normally a Firebase or Cloud JWT. A 'comfyui-' prefixed API key is also accepted in this header: the prefix classifies the value as an API key and it is validated exactly as if it had been sent in X-API-Key.

Path Parameters

provider
string
required

Lowercase provider segment of the canonical {provider}/{model} model ID - the partner whose model is being run. Lowercase provider segment of the canonical {provider}/{model} model ID - the partner whose model is being addressed. The invocation route's provider path parameter and a catalog entry's provider field both reference this one schema, which is what keeps the listed IDs and the accepted IDs from drifting apart.

Maximum string length: 64
Pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$
Example:

"bfl"

model
string
required

Lowercase model segment of the canonical {provider}/{model} model ID - the model to run within that provider. Lowercase model segment of the canonical {provider}/{model} model ID - the model to run within that provider. Shared by the invocation route's model path parameter and a catalog entry's model field, for the same no-drift reason as RouterProviderSegment.

Maximum string length: 128
Pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$
Example:

"flux-2-pro"

request_id
string<uuid>
required

The queued request to address - the request_id the submission returned in its body. It is not the submission's X-Comfy-Request-Id: that header carries the id of one HTTP call and addresses nothing, as the RouterQueueRequestId schema spells out. Identifier of one queued Router request - the handle a caller polls, cancels and collects a result by.

Maximum string length: 36
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"6f1a1a6e-6a53-4a5f-9d3a-2b3b0a1f9c21"

Response

OK - the request's current queue state. status is one of the three states; queue_position is present while the request is still IN_QUEUE; error_type is present only on a COMPLETED request that failed or was cancelled. X-Comfy-Credits-Used is present on a request that completed successfully once its cost is known, with the value the result collect carries.

One queued request's current state, composed with the same three URLs the submission returned.

status_url
string<uri>
required

Absolute URL of this request's status read.

Example:

"https://api.comfy.org/v2/models/bfl/flux-pro-1.1/requests/6f1a1a6e-6a53-4a5f-9d3a-2b3b0a1f9c21/status"

response_url
string<uri>
required

Absolute URL this request's result is collected from.

Example:

"https://api.comfy.org/v2/models/bfl/flux-pro-1.1/requests/6f1a1a6e-6a53-4a5f-9d3a-2b3b0a1f9c21"

cancel_url
string<uri>
required

Absolute URL a cancellation is asked for at.

Example:

"https://api.comfy.org/v2/models/bfl/flux-pro-1.1/requests/6f1a1a6e-6a53-4a5f-9d3a-2b3b0a1f9c21/cancel"

request_id
string<uuid>
required

Identifier of one queued Router request - the handle a caller polls, cancels and collects a result by.

Maximum string length: 36
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"6f1a1a6e-6a53-4a5f-9d3a-2b3b0a1f9c21"

status
enum<string>
required

The state of a queued Router request. It has exactly three values, and unlike RouterErrorType this one is a closed enum, because the two schemas are closed in opposite directions on purpose. RouterErrorType classifies failures and its set is expected to grow, so a generated client that hard-rejected an unrecognised bucket would fail hardest exactly when something had already gone wrong. This one is a lifecycle, and a lifecycle with a fourth state added later is a breaking change to every polling loop written against it whether it is declared as an enum or not - so it is declared as one, and the constraint is stated where a client can see it.

Available options:
IN_QUEUE,
IN_PROGRESS,
COMPLETED
Example:

"IN_QUEUE"

queue_position
integer

How many requests are ahead of this one in the queue, at the instant the response was composed. Zero means this request is at the front.

Required range: x >= 0
Example:

3

error_type
string

Present only on a COMPLETED request that did not succeed, carrying the same coarse bucket the result read puts on X-Comfy-Error-Type when it returns that failure. It is what distinguishes a terminal request that succeeded from one that failed or was cancelled - there is no separate terminal status for either - and it is absent on success rather than null, so branch on its presence.

Example:

"invalid_input"