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

# Create Workflow Run

> Start an agent conducting a workflow on a lead

Create a workflow run: one agent conducting one workflow on one lead. Get the `agentId` from [List Agents](/api-reference/agents/list-agents) and the `workflowId` from [List Workflows](/api-reference/workflows/list-workflows).

Depending on the workflow's type, the agent may begin sending messages to the lead.

## Authentication

Requires the `x-api-key` header with a valid workspace API key.

## Body Parameters

<ParamField body="leadId" type="string" required>
  The lead the workflow is conducted on.
</ParamField>

<ParamField body="agentId" type="string" required>
  The agent that conducts the workflow.
</ParamField>

<ParamField body="workflowId" type="string" required>
  The workflow the agent conducts.
</ParamField>

No other fields are accepted.

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="workflowRun" type="object">
  The new workflow run. See [Get Workflow Run](/api-reference/workflow-runs/get-workflow-run)
  for the full shape. A new workflow run is always `ACTIVE`.
</ResponseField>

## Errors

<ResponseField name="400" type="error">
  `leadId`, `agentId`, or `workflowId` is missing, or the body carries an
  unrecognized field.
</ResponseField>

<ResponseField name="404" type="error">
  The `leadId`, `agentId`, or `workflowId` isn't in your workspace.
</ResponseField>

<ResponseField name="409" type="error">
  The workflow run cannot be created:

  * **`Agent is already linked to this lead`**: this agent already has an open
    (`ACTIVE` or `PAUSED`) workflow run on this lead. Cancel or complete it first, or
    use a different agent.
  * **`… already collects this lead's checklist`**: a lead can have only one
    open `CHECKLIST` workflow run at a time.
  * **`This reminder workflow has no schedule configured yet`**: the
    `REMINDER` workflow needs a schedule set in the Monumint app first.
</ResponseField>

<RequestExample>
  ```javascript Node.js theme={null}
  const options = {
    method: "POST",
    headers: {
      "x-api-key": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      leadId: "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
      agentId: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      workflowId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    }),
  };

  fetch("https://api-v2.getomni.ai/api/v1/workflow-runs", options)
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api-v2.getomni.ai/api/v1/workflow-runs"
  headers = {"x-api-key": "<your-api-key>", "Content-Type": "application/json"}
  payload = {
      "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
      "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  }

  response = requests.request("POST", url, headers=headers, json=payload)
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api-v2.getomni.ai/api/v1/workflow-runs \
    --header 'x-api-key: <your-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
      "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "workflowRun": {
      "id": "5d8c1b2a-3e4f-5061-7283-94a5b6c7d8e9",
      "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
      "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "ACTIVE",
      "createdAt": "2026-09-10T17:42:03.000Z",
      "completedAt": null,
      "cancelledAt": null
    }
  }
  ```
</ResponseExample>