Create Async Run

Create Run With Api Key

curl --request POST \
  --url https://api.example.com/v1/workflows/{workflow_id}/runs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "input": {},
  "node_ids": [
    "<string>"
  ],
  "single_node_id": "<string>",
  "group_id": "<string>",
  "workflow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tracing": false,
  "debugger": "<string>",
  "callback_url": "<string>"
}
'

import requests

url = "https://api.example.com/v1/workflows/{workflow_id}/runs"

payload = {
    "input": {},
    "node_ids": ["<string>"],
    "single_node_id": "<string>",
    "group_id": "<string>",
    "workflow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tracing": False,
    "debugger": "<string>",
    "callback_url": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: {},
    node_ids: ['<string>'],
    single_node_id: '<string>',
    group_id: '<string>',
    workflow_version_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    tracing: false,
    debugger: '<string>',
    callback_url: '<string>'
  })
};

fetch('https://api.example.com/v1/workflows/{workflow_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/workflows/{workflow_id}/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => [
        
    ],
    'node_ids' => [
        '<string>'
    ],
    'single_node_id' => '<string>',
    'group_id' => '<string>',
    'workflow_version_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'tracing' => false,
    'debugger' => '<string>',
    'callback_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/workflows/{workflow_id}/runs"

	payload := strings.NewReader("{\n  \"input\": {},\n  \"node_ids\": [\n    \"<string>\"\n  ],\n  \"single_node_id\": \"<string>\",\n  \"group_id\": \"<string>\",\n  \"workflow_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"tracing\": false,\n  \"debugger\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/workflows/{workflow_id}/runs")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {},\n  \"node_ids\": [\n    \"<string>\"\n  ],\n  \"single_node_id\": \"<string>\",\n  \"group_id\": \"<string>\",\n  \"workflow_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"tracing\": false,\n  \"debugger\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/workflows/{workflow_id}/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": {},\n  \"node_ids\": [\n    \"<string>\"\n  ],\n  \"single_node_id\": \"<string>\",\n  \"group_id\": \"<string>\",\n  \"workflow_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"tracing\": false,\n  \"debugger\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "group_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "input": {},
  "output": {},
  "node_ids": [
    "<string>"
  ],
  "single_node_id": "<string>",
  "workflow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "progress_details": {
    "executed_nodes": [
      "<string>"
    ],
    "remaining_nodes": [
      "<string>"
    ],
    "per_node_progress": {},
    "running_nodes": [
      "<string>"
    ],
    "skipped_nodes": [],
    "error_handler_nodes": [],
    "subflow_executions": {},
    "per_edge_progress": {},
    "run_logs": {}
  },
  "progress": 0,
  "finished_at": "2023-11-07T05:31:56Z"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

workflows

{workflow_id}

runs

Create Run With Api Key

curl --request POST \
  --url https://api.example.com/v1/workflows/{workflow_id}/runs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "input": {},
  "node_ids": [
    "<string>"
  ],
  "single_node_id": "<string>",
  "group_id": "<string>",
  "workflow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tracing": false,
  "debugger": "<string>",
  "callback_url": "<string>"
}
'

import requests

url = "https://api.example.com/v1/workflows/{workflow_id}/runs"

payload = {
    "input": {},
    "node_ids": ["<string>"],
    "single_node_id": "<string>",
    "group_id": "<string>",
    "workflow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tracing": False,
    "debugger": "<string>",
    "callback_url": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: {},
    node_ids: ['<string>'],
    single_node_id: '<string>',
    group_id: '<string>',
    workflow_version_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    tracing: false,
    debugger: '<string>',
    callback_url: '<string>'
  })
};

fetch('https://api.example.com/v1/workflows/{workflow_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/workflows/{workflow_id}/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => [
        
    ],
    'node_ids' => [
        '<string>'
    ],
    'single_node_id' => '<string>',
    'group_id' => '<string>',
    'workflow_version_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'tracing' => false,
    'debugger' => '<string>',
    'callback_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/workflows/{workflow_id}/runs"

	payload := strings.NewReader("{\n  \"input\": {},\n  \"node_ids\": [\n    \"<string>\"\n  ],\n  \"single_node_id\": \"<string>\",\n  \"group_id\": \"<string>\",\n  \"workflow_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"tracing\": false,\n  \"debugger\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/workflows/{workflow_id}/runs")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {},\n  \"node_ids\": [\n    \"<string>\"\n  ],\n  \"single_node_id\": \"<string>\",\n  \"group_id\": \"<string>\",\n  \"workflow_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"tracing\": false,\n  \"debugger\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/workflows/{workflow_id}/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": {},\n  \"node_ids\": [\n    \"<string>\"\n  ],\n  \"single_node_id\": \"<string>\",\n  \"group_id\": \"<string>\",\n  \"workflow_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"tracing\": false,\n  \"debugger\": \"<string>\",\n  \"callback_url\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "group_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "input": {},
  "output": {},
  "node_ids": [
    "<string>"
  ],
  "single_node_id": "<string>",
  "workflow_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "progress_details": {
    "executed_nodes": [
      "<string>"
    ],
    "remaining_nodes": [
      "<string>"
    ],
    "per_node_progress": {},
    "running_nodes": [
      "<string>"
    ],
    "skipped_nodes": [],
    "error_handler_nodes": [],
    "subflow_executions": {},
    "per_edge_progress": {},
    "run_logs": {}
  },
  "progress": 0,
  "finished_at": "2023-11-07T05:31:56Z"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Parameters

Path Parameters

string

required

The ID of the workflow to run.

Body Parameters

object

required

Key-value pairs mapping input node labels (or IDs) to their values. The keys depend on how your workflow’s input nodes are configured.

{
  "User Question": "What is machine learning?",
  "Context": "Explain for a beginner"
}

string

Optional webhook URL. When the run reaches a terminal state (completed, failed, or stopped), the platform sends a POST request to this URL with the run result. Must be a valid HTTP(S) URL — invalid URLs are rejected with a 422 at creation time.

Show Webhook payload

Your endpoint receives a POST with Content-Type: application/json and the following body:

Field	Type	Description
`run_id`	`string`	The unique ID of the run
`workflow_id`	`string`	The workflow that was executed
`status`	`string`	Terminal status: `completed`, `failed`, or `stopped`
`outputs`	`object \| null`	The run’s output data (same structure as the GET run response)
`error`	`string \| null`	Error message if the run failed, `null` otherwise
`started_at`	`string \| null`	ISO 8601 timestamp when execution started
`completed_at`	`string \| null`	ISO 8601 timestamp when execution finished
`duration_ms`	`integer \| null`	Total execution time in milliseconds

Example payload:

{
  "run_id": "8e9e0b2d-768b-4697-ac0e-186f7b887b51",
  "workflow_id": "2d0a6b8e-7144-468d-acfd-c812cb4b4953",
  "status": "completed",
  "outputs": {
    "node-id::output": {
      "text": "The generated result...",
      "file": null
    }
  },
  "error": null,
  "started_at": "2025-06-15T10:30:00.000000",
  "completed_at": "2025-06-15T10:30:05.123456",
  "duration_ms": 5123
}

Show Delivery behavior

Retries: If your endpoint returns a non-2xx status or is unreachable, delivery is retried up to 3 times with exponential backoff (1s, 5s, 15s delays between attempts).
Timeout: Each delivery attempt times out after 10 seconds.
Non-blocking: Webhook delivery never affects run execution. If all retries fail, the run still completes normally — the webhook is simply not delivered.
Fire-on-terminal: Webhooks fire on all terminal states: completed, failed, and stopped (via the stop API).
Your endpoint should return a 2xx status code to acknowledge receipt.

string (uuid)

Run a specific saved version of the workflow. If omitted, the latest (current) version is used.

string[]

Limit execution to a subset of node IDs. Only these nodes (and their dependencies) will run. If omitted, the full workflow runs.

string

Run a single node in isolation. The provided input must satisfy all of the node’s input requirements.

boolean

default:"false"

Enable OpenTelemetry tracing for this run. Traces are sent to your configured observability provider.

string

Override the workspace (group) for this run. Defaults to the workspace associated with the API key.

string

Debugger session ID for live debugging in the workflow editor.

Examples

Basic run

curl -X POST https://backend.noxus.ai/v1/workflows/{workflow_id}/runs \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "User Question": "What are the benefits of renewable energy?"
    }
  }'

from noxus_sdk.client import Client

client = Client(api_key="your-api-key")
workflow = client.workflows.get("workflow-id")

run = workflow.run(body={
    "User Question": "What are the benefits of renewable energy?"
})

# Wait for completion
result = run.wait()
print(result.output)

Run with webhook callback

curl -X POST https://backend.noxus.ai/v1/workflows/{workflow_id}/runs \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "User Question": "Summarize this document"
    },
    "callback_url": "https://your-server.com/webhook/noxus"
  }'

run = workflow.run(
    body={"User Question": "Summarize this document"},
    callback_url="https://your-server.com/webhook/noxus"
)
# No need to poll — your server receives the result when done

Your webhook endpoint will receive a POST with:

{
  "run_id": "abc-123",
  "workflow_id": "wf-456",
  "status": "completed",
  "outputs": { ... },
  "error": null,
  "started_at": "2025-01-15T10:30:00.000000",
  "completed_at": "2025-01-15T10:30:05.000000",
  "duration_ms": 5000
}

Run a specific version

curl -X POST https://backend.noxus.ai/v1/workflows/{workflow_id}/runs \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"Query": "Hello"},
    "workflow_version_id": "version-uuid-here"
  }'

Authorizations

X-API-Key

string

header

required

Path Parameters

workflow_id

string

required

Body

application/json

input

Input · object

required

node_ids

string[] | null

single_node_id

string | null

group_id

string | null

workflow_version_id

string<uuid> | null

tracing

boolean

default:false

debugger

string | null

callback_url

string<uri> | null

Required string length: 1 - 2083

Response

Successful Response

SimplifiedRun for public API — excludes workflow_definition.

string<uuid>

required

group_id

string<uuid>

required

workflow_id

string<uuid>

required

status

enum<string>

required

Available options:

queued,

running,

failed,

completed,

stopped,

awaiting_human_feedback

created_at

string<date-time>

required

input

Input · object | null

output

Output · object | null

node_ids

single_node_id

string | null

workflow_version_id

string<uuid> | null

progress_details

WorkflowProgress · object | null

Show child attributes

progress

integer

default:0

finished_at

string<date-time> | null

⌘I

Introduction

Cookbook

Workflows

Runs

Conversations

Knowledge Base

Agents

Parameters

Path Parameters

Body Parameters

Examples

Basic run

Run with webhook callback

Run a specific version

Authorizations

Path Parameters

Body

Response

​Parameters

​Path Parameters

​Body Parameters

​Examples

​Basic run

​Run with webhook callback

​Run a specific version

Authorizations

Path Parameters

Body

Response

Parameters

Path Parameters

Body Parameters

Examples

Basic run

Run with webhook callback

Run a specific version