---
title: "Run a workflow"
method: POST
path: "/hub/workflows/{collection_topic}/{flow_topic}/run"
tags: ["Workflows"]
---

# Run a workflow

`POST /hub/workflows/{collection_topic}/{flow_topic}/run`

## Request

- Base URL: `https://api.quiva.ai`
- URL: `https://api.quiva.ai/hub/workflows/{collection_topic}/{flow_topic}/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/:collection_topic/:flow_topic/run/post.ts> (a function with typed inputs; its response is checked against the schema)

Executes a workflow with the specified trigger data

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`

Workflow executed successfully

- union
  - object
    - `trackingId` string: ID for tracking the workflow execution
    - `result` object: Result of the workflow execution
  - string: Status message for debounced or ordered executions

## Other responses

- `400`: Bad request
- `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 breaking, 6 info
  - added the new required request property `subject`
  - added the new optional request property `knowledge`
  - added the new optional request property `retry`
  - added the new optional request property `run_id`
  - …3 more
- **2025-07-09** `945cf8329cbe`: 1 warning, 1 info
  - removed the request property `subject`
  - added the new optional `query` request parameter `draft` to all path's operations
- **2025-06-06** `c94dfce6bc86`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway-3/changes/hub/workflows/:collection_topic/:flow_topic/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)