---
title: "Execute a workflow"
method: POST
path: "/hub/workflows/run"
---

# Execute a workflow

`POST /hub/workflows/run`

## Request

- Base URL: `https://api.quiva.ai`
- URL: `https://api.quiva.ai/hub/workflows/run`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-3/docs/hub/workflows/run/post.ts> (a function with typed inputs; its response is checked against the schema)

Run a published workflow. await=true returns results synchronously; await=false returns a tracking_id immediately. Resume a paused (input/human-in-the-loop) run by passing its run_id plus the human response as trigger.

Resuming a run that is not paused or errored answers 409; it does not start the flow again. The paused entry is claimed when the resume is accepted, so a second submit is refused. A call with `await: false` can now return an error, including start-up failures, and waits for the first stream write.

## Request body

- RunWorkflowRequest
  - `subject` string, required: Workflow subject. Published: ms.hub.config.workflow.{collection}.{flow} (NO 'published' segment - get it from listWorkflows version=published). Draft: ms.hub.config.workflow.draft.{collection}.{flow}.
  - `trigger` object: Run input, referenced in nodes via $.trigger
  - `triggers` object[]: Batch execution (use either trigger or triggers)
  - `await` boolean: true = wait for completion and return results; false = return tracking_id immediately
  - `enable_log` boolean: Store detailed run logs (searchable via searchRunLogs)
  - `knowledge` string[]: Knowledge URIs for agents: kv://, obj://, str://, sid://, dta://
  - `session_id` string: Agent conversation continuity; omit for new sessions
  - `run_id` string: Full tracking id of a paused or errored run to resume (human-in-the-loop), in the form ms.hub.run.<uuid>.<flow subject>, as returned when the run started and by the paused-runs list. A bare uuid is rejected with 400 invalid run_id. Resuming a run that is not paused or errored returns 409.
  - `retry` boolean: Retry a failed run

## Response `200`

Run result. { tracking_id, result }. If config.result was set, result matches that JSONPath selection; otherwise result is the step-by-step log array where items with a 'paused': true flag indicate a human-in-the-loop pause (resume with run_id).

## Other responses

- `400`: Invalid request or validation failure, e.g. { "error": "duplicate node id found: CODE_EXPERT" }
- `404`: Workflow not found or not published
- `409`: The run is not paused or errored, or there is no errors entry to retry. A second resume of the same pause is refused the same way.

## Changes

- **2026-11-12** `8730377687f9`: 1 info
  - endpoint added
- **2025-06-06** `c94dfce6bc86`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-3/changes/hub/workflows/run/post.md)

---

[API](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-3.md) - [All operations](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-3/llms.txt) - [OpenAPI document](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-3/revisions/f80cd5f3ac1c?raw)