Create Sync Run
curl --request POST \
--url https://api.example.com/v1/workflows/{workflow_id}/runs/sync \
--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/sync"
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/sync', 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/sync",
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/sync"
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/sync")
.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/sync")
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",
"output": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Create Sync Run
Create a run for a specific workflow synchronously
POST
/
v1
/
workflows
/
{workflow_id}
/
runs
/
sync
Create Sync Run
curl --request POST \
--url https://api.example.com/v1/workflows/{workflow_id}/runs/sync \
--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/sync"
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/sync', 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/sync",
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/sync"
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/sync")
.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/sync")
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",
"output": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}This endpoint creates and waits for a workflow run to complete before returning the result. It blocks until the run reaches a terminal state or the request times out (120 seconds max).
For long-running workflows, use the async run endpoint with SSE streaming or a
callback_url instead.
Parameters
Path Parameters
string
required
The ID of the workflow to run.
Query Parameters
boolean
default:"false"
When
true, the response contains only the workflow output (not the full run object). Useful when you only need the result.boolean
default:"false"
When
true, output keys use node IDs instead of human-readable labels.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. Even though this is a synchronous endpoint, you can still receive a webhook callback when the run completes. Must be a valid HTTP(S) URL — invalid URLs are rejected with a
422 at creation time.Show Webhook payload
Show Webhook payload
Your endpoint receives a
Example payload:
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 |
{
"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
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, andstopped(via the stop API). - Your endpoint should return a
2xxstatus 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 synchronous run
curl -X POST https://backend.noxus.ai/v1/workflows/{workflow_id}/runs/sync \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"input": {
"User Question": "What are the benefits of renewable energy?"
}
}'
import httpx
response = httpx.post(
"https://backend.noxus.ai/v1/workflows/{workflow_id}/runs/sync",
headers={"X-API-Key": "your-api-key"},
json={
"input": {"User Question": "What are the benefits of renewable energy?"}
},
timeout=120,
)
result = response.json()
print(result["output"])
Output only
Returns just the workflow output without the full run metadata:curl -X POST "https://backend.noxus.ai/v1/workflows/{workflow_id}/runs/sync?output_only=true" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"input": {"Query": "Summarize this"}
}'
Run a specific version
curl -X POST https://backend.noxus.ai/v1/workflows/{workflow_id}/runs/sync \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"input": {"Query": "Hello"},
"workflow_version_id": "version-uuid-here"
}'
Authorizations
Path Parameters
Body
application/json