Skip to main content
POST
/
v1
/
models
/
{owner}
/
{slug}
/
runs
Create and dispatch a singleton model run
curl --request POST \
  --url https://api.runflow.io/v1/models/{owner}/{slug}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": {},
  "metadata": {},
  "callback_url": "<string>",
  "client_ref": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "comfyui_workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "target_type": "model",
  "target_version": "<string>",
  "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status_code": "queued",
  "source_code": "playground",
  "input": {},
  "output": {},
  "context": {},
  "duration_ms": 123,
  "cost": "<string>",
  "cost_breakdown": {},
  "nodes_total": 123,
  "nodes_completed": 123,
  "resolved_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "client_ref": "<string>",
  "jurisdiction_code": "<string>",
  "flow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "request_id": "<string>",
  "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "callback_url": "<string>",
  "metadata": {},
  "has_logs": true,
  "has_node_runs": true,
  "links": {},
  "failure_code": "<string>",
  "failure_message": "<string>",
  "failure_stage_code": "dispatch",
  "node_runs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "node_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "state_code": "<string>",
      "input": {},
      "output": {},
      "input_signature": "<string>",
      "preview_type": "<string>",
      "preview_value": "<string>",
      "duration_ms": 123,
      "cost": "<string>",
      "retry_count": 123,
      "error_message": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    }
  ],
  "logs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "level_code": "<string>",
      "message": "<string>",
      "timestamp": "2023-11-07T05:31:56Z",
      "meta": {},
      "run": null
    }
  ],
  "model": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model_creator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "slug": "<string>",
    "name": "<string>",
    "description": "<string>",
    "version": "<string>",
    "is_public": true,
    "is_open_source": true,
    "icon_url": "<string>",
    "cover_url": "<string>",
    "category_code": "<string>",
    "status_code": "<string>",
    "family_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "family_variant_code": "<string>",
    "param_count": "<string>",
    "architecture": "<string>",
    "license_code": "<string>",
    "max_resolution": "<string>",
    "lora_support": true,
    "fine_tuning": true,
    "supports_streaming": true,
    "paper_url": "<string>",
    "github_url": "<string>",
    "is_official": true,
    "availability_status": "<string>",
    "seo": {},
    "notable_features": [
      "<unknown>"
    ],
    "content": "<string>",
    "pricing_note": "<string>",
    "created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "deleted_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "inputs": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "display_name": "<string>",
        "description": "<string>",
        "variable_type_code": "<string>",
        "default_behavior_code": "<string>",
        "validator_code": "<string>",
        "validator_attrs": {},
        "is_required": true,
        "default_value": {},
        "sort_order": 123,
        "is_featured": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "outputs": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "display_name": "<string>",
        "description": "<string>",
        "variable_type_code": "<string>",
        "validator_code": "<string>",
        "validator_attrs": {},
        "sort_order": 123,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "examples": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "title": "<string>",
        "description": "<string>",
        "input": {},
        "output": {},
        "status_code": 123,
        "cost": "<string>",
        "start_type": "<string>",
        "timing": {},
        "duration_ms": 123,
        "total_ms": 123,
        "thumbnail_url": "<string>",
        "category_code": "<string>",
        "is_featured": true,
        "is_public": true,
        "sort_order": 123,
        "ran_at": "2023-11-07T05:31:56Z",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "faq_entries": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "question": "<string>",
        "answer": "<string>",
        "sort_order": 123,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "pricing": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "pricing_model_code": "<string>",
        "rule_effect_code": "<string>",
        "model_input_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "match_value": null,
        "dimension_code": "<string>",
        "min_value": "<string>",
        "max_value": "<string>",
        "price": "<string>",
        "currency_code": "<string>",
        "unit_code": "<string>",
        "multiplier_label": "<string>",
        "description": "<string>",
        "sort_order": 123,
        "disabled_at": "2023-11-07T05:31:56Z",
        "measurement_source": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "related_links": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "related_model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "sort_order": 123,
        "created_at": "2023-11-07T05:31:56Z"
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

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
​
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
​
output
Output · object
​
context
Context · object
​
duration_ms
integer | null
​
cost
string | null
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
cost_breakdown
Cost Breakdown · object
​
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
​
has_logs
boolean | null
​
has_node_runs
boolean | null
​
links
Links · object
​
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
​
node_runs
FullValidator · object[] | null
​
logs
FullValidator · object[] | null
​
model
FullValidator · object

Response shape.