Skip to main content
POST
Create and dispatch a singleton model run

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Organization-Id
string | null

Path Parameters

owner
string
required
slug
string
required

Body

application/json

POST body for creating a singleton model run.

client_ref is an optional Run-level customer correlation label (≤255 chars), echoed in responses and webhook payloads; not sent to providers, not used for billing, not an idempotency key. It is a top-level transport field, NOT a member of input.

input
Input · object
required
metadata
Metadata · object | null
callback_url
string | null
client_ref
string | null
Maximum string length: 255

Response

Successful Response

Response shape.

id
string<uuid> | null
flow_id
string<uuid> | null
model_id
string<uuid> | null
comfyui_workflow_id
string<uuid> | null
target_type
enum<string> | null
Available options:
model,
flow,
comfyui
target_version
string | null
org_id
string<uuid> | null
status_code
enum<string> | null
Available options:
queued,
dispatching,
running,
succeeded,
failed,
cancelled,
partial_succeeded
source_code
enum<string> | null
Available options:
playground,
api,
flow-node
input
Input · object | null
output
Output · object | null
context
Context · object | null
duration_ms
integer | null
cost
string | null
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
cost_breakdown
Cost Breakdown · object | null
nodes_total
integer | null
nodes_completed
integer | null
resolved_template_id
string<uuid> | null
batch_id
string<uuid> | null
client_ref
string | null
jurisdiction_code
string | null
flow_version_id
string<uuid> | null
request_id
string | null
created_by
string<uuid> | null
created_at
string<date-time> | null
started_at
string<date-time> | null
completed_at
string<date-time> | null
callback_url
string | null
metadata
Metadata · object | null
has_logs
boolean | null
has_node_runs
boolean | null
links
Links · object | null
failure_code
string | null

Failure classification (FK to run_failure_codes.code). None on successful runs.

failure_message
string | null

Human-readable failure detail. See /v1/runs/{id}/logs for full audit history.

failure_stage_code
enum<string> | null

Pipeline stage where the failure originated (FK to run_failure_stages.code).

Available options:
dispatch,
execution,
callback,
reconciliation
feedback_is_positive
boolean | null

Customer thumb (TRUE = 👍, FALSE = 👎, NULL = no rating yet).

feedback_reason
string | null

Optional customer-supplied note explaining the feedback.

source_chat_message_id
string<uuid> | null

Chat message that dispatched this run, if any.

current_evaluation_summary
RunEvaluationSummary · object | null

Slim projection of a run's current evaluation, surfaced as the current_evaluation_summary custom embed on GET /v1/runs.

"Current" = status_code == 'completed' AND superseded_at IS NULL. The embed loader (routers/runs._populate_evaluation_summary) writes None for runs with no current evaluation so the wire shape is {"current_evaluation_summary": null} rather than an absent key once the caller opts into the embed. The field is gated behind evaluations:read — see _RUN_CUSTOM_EMBED_PERMISSIONS.

status_code is typed as Literal["completed"] because the loader's subquery (RunRepository._current_evaluation) filters to completed rows only; any other value would be a contract violation.

node_runs
FullValidator · object[] | null
logs
FullValidator · object[] | null
model
FullValidator · object | null

Response shape.

comfyui_workflow
FullValidator · object | null

Response shape.