> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Sync Run

> Create a run for a specific workflow synchronously

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](/api-reference/v1/runs/create-run-with-api-key) with [SSE streaming](/api-reference/v1/runs/public-run-events) or a `callback_url` instead.

## Parameters

### Path Parameters

<ParamField path="workflow_id" type="string" required>
  The ID of the workflow to run.
</ParamField>

### Query Parameters

<ParamField query="output_only" type="boolean" default="false">
  When `true`, the response contains only the workflow output (not the full run object). Useful when you only need the result.
</ParamField>

<ParamField query="use_output_ids" type="boolean" default="false">
  When `true`, output keys use node IDs instead of human-readable labels.
</ParamField>

### Body Parameters

<ParamField body="input" type="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.

  ```json theme={null}
  {
    "User Question": "What is machine learning?",
    "Context": "Explain for a beginner"
  }
  ```
</ParamField>

<ParamField body="callback_url" type="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.

  <Expandable title="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:

    ```json theme={null}
    {
      "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
    }
    ```
  </Expandable>

  <Expandable title="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.
  </Expandable>
</ParamField>

<ParamField body="workflow_version_id" type="string (uuid)">
  Run a specific saved version of the workflow. If omitted, the latest (current) version is used.
</ParamField>

<ParamField body="node_ids" type="string[]">
  Limit execution to a subset of node IDs. Only these nodes (and their dependencies) will run. If omitted, the full workflow runs.
</ParamField>

<ParamField body="single_node_id" type="string">
  Run a single node in isolation. The provided `input` must satisfy all of the node's input requirements.
</ParamField>

<ParamField body="tracing" type="boolean" default="false">
  Enable OpenTelemetry tracing for this run. Traces are sent to your configured observability provider.
</ParamField>

<ParamField body="group_id" type="string">
  Override the workspace (group) for this run. Defaults to the workspace associated with the API key.
</ParamField>

<ParamField body="debugger" type="string">
  Debugger session ID for live debugging in the workflow editor.
</ParamField>

## Examples

### Basic synchronous run

<CodeGroup>
  ```bash cURL theme={null}
  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?"
      }
    }'
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

### Output only

Returns just the workflow output without the full run metadata:

```bash theme={null}
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

```bash theme={null}
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"
  }'
```


## OpenAPI

````yaml post /v1/workflows/{workflow_id}/runs/sync
openapi: 3.1.0
info:
  title: Noxus Backend
  description: >-
    Backend API for the Noxus Platform. More information can be found at
    https://docs.noxus.ai
  version: 1.1.0
servers: []
security: []
paths:
  /v1/workflows/{workflow_id}/runs/sync:
    post:
      tags:
        - V1 - Runs
      summary: Create Sync Run
      operationId: create_sync_run
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
            title: Workflow Id
        - name: output_only
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Output Only
        - name: use_output_ids
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Use Output Ids
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/RunOutput'
                  - $ref: '#/components/schemas/PublicSimplifiedRun'
                title: Response Create Sync Run
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    CreateRunRequest:
      properties:
        input:
          additionalProperties: true
          type: object
          title: Input
        node_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Node Ids
        single_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Single Node Id
        group_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Group Id
        workflow_version_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workflow Version Id
        tracing:
          type: boolean
          title: Tracing
          default: false
        debugger:
          anyOf:
            - type: string
            - type: 'null'
          title: Debugger
        callback_url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: Callback Url
      type: object
      required:
        - input
      title: CreateRunRequest
    RunOutput:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        output:
          additionalProperties: true
          type: object
          title: Output
      type: object
      required:
        - id
        - output
      title: RunOutput
    PublicSimplifiedRun:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        group_id:
          type: string
          format: uuid
          title: Group Id
        workflow_id:
          type: string
          format: uuid
          title: Workflow Id
        input:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Input
        output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output
        node_ids:
          anyOf:
            - items:
                type: string
              type: array
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Node Ids
        single_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Single Node Id
        workflow_version_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workflow Version Id
        progress_details:
          anyOf:
            - $ref: '#/components/schemas/WorkflowProgress'
            - type: 'null'
        status:
          $ref: '#/components/schemas/RunStatus'
        progress:
          type: integer
          title: Progress
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
      type: object
      required:
        - id
        - group_id
        - workflow_id
        - status
        - created_at
      title: PublicSimplifiedRun
      description: SimplifiedRun for public API — excludes workflow_definition.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WorkflowProgress:
      properties:
        executed_nodes:
          items:
            type: string
          type: array
          title: Executed Nodes
        running_nodes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Running Nodes
        remaining_nodes:
          items:
            type: string
          type: array
          title: Remaining Nodes
        skipped_nodes:
          items:
            type: string
          type: array
          title: Skipped Nodes
          default: []
        error_handler_nodes:
          items:
            type: string
          type: array
          title: Error Handler Nodes
          default: []
        per_node_progress:
          additionalProperties:
            $ref: '#/components/schemas/NodeProgress'
          type: object
          title: Per Node Progress
        subflow_executions:
          additionalProperties:
            $ref: '#/components/schemas/SubflowExecution'
          type: object
          title: Subflow Executions
          default: {}
        per_edge_progress:
          additionalProperties:
            $ref: '#/components/schemas/EdgeProgress'
          type: object
          title: Per Edge Progress
          default: {}
        run_logs:
          additionalProperties:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
              - type: number
              - type: integer
          type: object
          title: Run Logs
      type: object
      required:
        - executed_nodes
        - remaining_nodes
        - per_node_progress
      title: WorkflowProgress
    RunStatus:
      type: string
      enum:
        - queued
        - running
        - failed
        - completed
        - stopped
        - awaiting_human_feedback
      title: RunStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    NodeProgress:
      properties:
        current_it:
          type: integer
          title: Current It
        total_it:
          type: integer
          title: Total It
        status:
          $ref: '#/components/schemas/NodeStatus'
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
        warnings:
          items:
            $ref: '#/components/schemas/SpotWarning'
          type: array
          title: Warnings
      type: object
      required:
        - current_it
        - total_it
        - status
      title: NodeProgress
    SubflowExecution:
      properties:
        node_id:
          type: string
          title: Node Id
        workflow_name:
          type: string
          title: Workflow Name
        workflow_id:
          type: string
          title: Workflow Id
        workflow_definition:
          $ref: '#/components/schemas/WorkflowDefinition'
        raw_definition:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Raw Definition
        total_iterations:
          type: integer
          title: Total Iterations
        iterations:
          additionalProperties:
            $ref: '#/components/schemas/WorkflowProgress'
          type: object
          title: Iterations
          default: {}
      type: object
      required:
        - node_id
        - workflow_name
        - workflow_id
        - workflow_definition
        - total_iterations
      title: SubflowExecution
      description: >-
        Some important notes:

        - This stores metadata needed to display subflow results in the
        frontend.

        - The workflow_definition is shared across all iterations (stored once).

        - Each iteration's progress is stored separately in the iterations dict.


        The raw_definition is stored for resume purposes - when resuming a
        paused

        subflow (e.g., after HITL), we must use the exact same workflow
        definition

        that was used originally, not the potentially-modified current version.
    EdgeProgress:
      properties:
        status:
          $ref: '#/components/schemas/EdgeStatus'
          default: pending
      type: object
      title: EdgeProgress
    NodeStatus:
      type: string
      enum:
        - running
        - errored
        - succeeded
        - skipped
        - payment_required
        - awaiting_human_feedback
      title: NodeStatus
    SpotWarning:
      properties:
        detail:
          type: string
          title: Detail
        identifier:
          $ref: '#/components/schemas/WarningIdentifier'
        node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Node Id
        params:
          additionalProperties: true
          type: object
          title: Params
          default: {}
        markdown:
          anyOf:
            - type: string
            - type: 'null'
          title: Markdown
        snippet:
          anyOf:
            - type: string
            - type: 'null'
          title: Snippet
      type: object
      required:
        - detail
        - identifier
      title: SpotWarning
    WorkflowDefinition:
      properties:
        nodes:
          items:
            $ref: '#/components/schemas/NodePreview'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/EdgePreview'
          type: array
          title: Edges
      type: object
      required:
        - nodes
        - edges
      title: WorkflowDefinition
    EdgeStatus:
      type: string
      enum:
        - pending
        - active
        - skipped
        - completed
      title: EdgeStatus
    WarningIdentifier:
      type: string
      enum:
        - general
        - model_fallback
        - model_timeout
        - reading_spreadsheet
        - invalid_search
        - no_results_returned
        - integration_warning
        - failed_scraping
        - invalid_value
        - continue_on_error
        - data_ingestion
        - document_already_exists
        - ingestion_timeout
        - libreoffice_conversion
        - low_confidence
        - guardrail_validation
        - kb_creation
        - kb_empty
        - unsupported_qa_file_type
        - unsupported_file_type
        - no_files_to_add_to_kb
        - no_files_added_to_kb
        - no_google_drive_files
        - no_one_drive_files
        - no_sharepoint_files
        - no_websites_scraped
        - websites_failed_scraping
        - empty_file
        - document_overwrite
        - no_content_provided
        - invalid_folder
        - document_name_too_long
        - retry_warning
      title: WarningIdentifier
    NodePreview:
      properties:
        node_config:
          additionalProperties: true
          type: object
          title: Node Config
        connector_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Connector Config
        credential_ids:
          additionalProperties:
            type: string
          type: object
          title: Credential Ids
          default: {}
        subflow_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Subflow Id
        id:
          type: string
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        type:
          type: string
          title: Type
        subflow_config:
          anyOf:
            - $ref: '#/components/schemas/SubflowConfig'
            - type: 'null'
        plugin_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Plugin Name
      type: object
      required:
        - node_config
        - id
        - type
      title: NodePreview
    EdgePreview:
      properties:
        from_id:
          $ref: '#/components/schemas/ConnectorAddress'
        to_id:
          $ref: '#/components/schemas/ConnectorAddress'
        id:
          type: string
          title: Id
      type: object
      required:
        - from_id
        - to_id
        - id
      title: EdgePreview
    SubflowConfig:
      properties:
        workflow_id:
          type: string
          title: Workflow Id
        workflow_name:
          type: string
          title: Workflow Name
        workflow_nodes:
          items:
            type: string
          type: array
          title: Workflow Nodes
          default: []
      type: object
      required:
        - workflow_id
        - workflow_name
      title: SubflowConfig
    ConnectorAddress:
      properties:
        connector_name:
          type: string
          title: Connector Name
        node_id:
          type: string
          title: Node Id
        key:
          anyOf:
            - type: string
            - type: 'null'
          title: Key
        optional:
          type: boolean
          title: Optional
          default: false
      type: object
      required:
        - connector_name
        - node_id
      title: ConnectorAddress
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````