---
title: "Execute Workflow (v2 sync or stream)"
method: POST
path: "/api/v2/workflows"
tags: ["Workflow"]
---

# Execute Workflow (v2 sync or stream)

`POST /api/v2/workflows`

## Request body

- WorkflowRunRequest — Request schema for ``POST /api/v2/workflows`` (v2 native body). First-class fields for everything callers actually configure when running a flow. Streaming protocol is selected by ``stream_protocol``; the endpoint validates it against the live adapter registry and returns 422 with the available list when unknown.
  - `data` object, nullable — Optional live-canvas override of the flow's nodes/edges; takes priority over the saved flow data.
  - `files` string[], nullable — Optional list of pre-uploaded file paths to attach to the run.
  - `flow_id` string, required — UUID of the flow to run.
  - `globals` object — Request-level global variables made available to workflow components. Keys may use any printable string up to 256 chars; values are capped at 65536 chars. Body globals always win over the legacy ``X-LANGFLOW-GLOBAL-VAR-*`` headers. Honored in sync mode; ignored for stream/background modes.
  - `idempotency_key` string, nullable — Optional client-supplied key that dedupes background submits. Two background runs with the same key return the same job_id instead of queuing duplicate work. Ignored for sync/stream modes.
  - `input_value` string — Chat-style input value.
  - `mode` 'sync' | 'stream' | 'background' — Execution mode for a v2 workflow run.
  - `output_ids` string[], nullable — Component ids of the outputs you want as the answer (sync mode). When set, ``output.text`` resolves among only these, so naming one text output makes ``output.reason`` deterministic on multi-output flows. The full ``outputs`` map is still returned. Ids must be outputs of this flow or the request is rejected before the flow runs. Ignored for stream/background modes.
  - `session_id` string, nullable — When set, message memory and chat history scope to this session.
  - `start_component_id` string, nullable — Partial-run start component id.
  - `stop_component_id` string, nullable — Partial-run stop component id.
  - `stream_protocol` string — Wire protocol for streaming events. Defaults to ``langflow`` (raw EventManager payloads). ``agui`` emits AG-UI events. Unknown values return 422 with the available list. Ignored when mode=sync.
  - `tweaks` object — Per-component parameter overrides keyed by component id.

## Response `200`

Workflow execution response

- union
  - object — Synchronous workflow execution response.
    - `created_timestamp` string
    - `errors` ErrorDetail[]
      - `code` string, nullable
      - `details` object, nullable
      - `error` string, required
    - `flow_id` string, required
    - `globals` object
    - `human_request` object, nullable — Set when ``status`` is ``suspended``: the human-input request the run paused on (``prompt``, ``options``, ``allowed_decisions``, ``request_id``). Resume by running the same session/task again with the chosen decision.
    - `inputs` object
    - `job_id` union
      - string
      - string, uuid
    - `object` 'response'
    - `output` WorkflowOutput — The run's primary text answer plus the reason it resolved that way.
      - `reason` 'single' | 'multiple' | 'none' | 'non_string' | 'failed', required — Why ``WorkflowOutput.text`` resolved the way it did. Mirrors the LLM-domain ``finish_reason`` / ``stop_reason`` convention: a machine-readable enum explaining the disposition of the answer, distinct from the lifecycle ``status``.
      - `source` string, nullable — Component id that produced ``text``. Set only when ``reason`` is ``single``.
      - `text` string, nullable — The run's text answer. Set only when ``reason`` is ``single``. Empty string is a valid answer.
    - `outputs` object
    - `session_id` string, nullable — The session the run executed under. Echoes the request ``session_id`` when provided, otherwise the server-generated one. Pass it back on the next call to continue the same chat history / memory thread.
    - `status` 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'suspended', required — Job execution status.
  - object — Background job response.
    - `created_timestamp` string
    - `errors` ErrorDetail[]
      - `code` string, nullable
      - `details` object, nullable
      - `error` string, required
    - `flow_id` string, required
    - `globals` object
    - `job_id` union, required
      - string
      - string, uuid
    - `links` object
    - `object` 'job'
    - `status` 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'suspended', required — Job execution status.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/langflow-ai/apis/langflow.md) · [All operations](https://skmtc.net/langflow-ai/apis/langflow/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langflow-ai/langflow/revisions/22962dc5e81b/schema)