# Start workflow job

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Initiates an execution for the specified workflow. After the request is successful, save the returned execution ID, and then query the status and results of the job; a successful request does not mean that the workflow has been completed.

```text
POST https://moi.matrixorigin.cn/newmoi/workflow/v2/workflow-apps/{workflow_id}/executions
```

## Preparation before calling

First [View workflow details](../workflows/get-workflow.md#successful-response) to confirm the runtime fields and execution configuration of the workflow. Prepare a personal access token and target workspace ID that has access to the target workspace.

The request body cannot contain `runtime_context`.

## Request body

::::{div} mo-api-split
:::{div} mo-api-split-main

```{raw} html
<dl class="mo-api-fields">
  <div class="mo-api-field"><dt><code>workflow_id</code><span class="mo-api-field__type">string</span><span class="mo-api-field__required">Required</span></dt><dd>The ID of the workflow to run.</dd></div>
  <div class="mo-api-field"><dt><code>values</code><span class="mo-api-field__type">object</span></dt><dd>Input value keyed by runtime form `field_id`. The server will merge it with the workflow default values ​​and verify the required fields.</dd></div>
  <div class="mo-api-field"><dt><code>trigger_now</code><span class="mo-api-field__type">boolean</span></dt><dd>Whether to trigger execution immediately.</dd></div>
  <div class="mo-api-field"><dt><code>run_once</code><span class="mo-api-field__type">boolean</span></dt><dd>When the Cron workflow is set to `true`, this run will be processed as a one-time execution.</dd></div>
  <div class="mo-api-field"><dt><code>execution_mode</code><span class="mo-api-field__type">string</span></dt><dd>Passing in is not supported; passing in a non-null value will return a parameter error. The execution mode is determined by the published workflow.</dd></div>
  <div class="mo-api-field"><dt><code>compute_resource_id</code><span class="mo-api-field__type">string</span></dt><dd>The computing resource ID used for this run.</dd></div>
</dl>
```

:::
:::{div} mo-api-split-aside

```{raw} html
<p class="mo-api-example-label">Request example</p>
```

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workflow/v2/workflow-apps/$WORKFLOW_ID/executions" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "values": {
      "<FIELD_ID>": "<VALUE>"
    },
    "trigger_now": true
  }'
```

:::
::::

## Successful response

Returns `200` on success. Acceptance of the request does not mean that the execution is completed; save the `data.workflow_run.execution_id` and use it to query job details and results.

::::{div} mo-api-split
:::{div} mo-api-split-main

```{raw} html
<dl class="mo-api-fields">
  <div class="mo-api-field"><dt><code>code</code><span class="mo-api-field__type">string</span></dt><dd>`OK` when successful.</dd></div>
  <div class="mo-api-field"><dt><code>msg</code><span class="mo-api-field__type">string</span></dt><dd>`OK` when successful.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.execution_id</code><span class="mo-api-field__type">string</span></dt><dd>The execution ID of the new job.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.workflow_id</code><span class="mo-api-field__type">string</span></dt><dd>Workflow ID.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.status</code><span class="mo-api-field__type">string</span></dt><dd>Current execution status when created; query should continue to confirm the final status.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.available_actions</code><span class="mo-api-field__type">string[]</span></dt><dd>Follow-up actions allowed by the current state.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.execution_mode</code><span class="mo-api-field__type">string</span></dt><dd>The mode used for this execution.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.moi_task_id</code><span class="mo-api-field__type">string</span></dt><dd>Task ID returned when assigned by the server.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.moi_case_id</code><span class="mo-api-field__type">string</span></dt><dd>Case ID returned when assigned by the server.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.moi_workflow_def_id</code><span class="mo-api-field__type">string</span></dt><dd>Workflow definition ID associated with this execution.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.moi_workflow_version_id</code><span class="mo-api-field__type">string</span></dt><dd>Workflow version ID associated with this execution.</dd></div>
  <div class="mo-api-field"><dt><code>data.workflow_run.error</code><span class="mo-api-field__type">string</span></dt><dd>Current error; returned if there is a value.</dd></div>
</dl>
```

:::
:::{div} mo-api-split-aside

```{raw} html
<p class="mo-api-example-label">Successful response example</p>
```

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workflow_run": {
      "execution_id": "exec-001",
      "workflow_id": "wf-001",
      "status": "ready",
      "available_actions": ["cancel"],
      "execution_mode": "one_shot",
      "moi_task_id": "task-001",
      "moi_case_id": "case-001",
      "moi_workflow_def_id": "def-001",
      "moi_workflow_version_id": "ver-001"
    }
  }
}
```

:::
::::

## Error response

::::{div} mo-api-split
:::{div} mo-api-split-main

```{raw} html
<dl class="mo-api-fields">
  <div class="mo-api-field"><dt><code>code</code><span class="mo-api-field__type">string</span></dt><dd>Error code.</dd></div>
  <div class="mo-api-field"><dt><code>msg</code><span class="mo-api-field__type">string</span></dt><dd>Readable error message.</dd></div>
  <div class="mo-api-field"><dt><code>data</code><span class="mo-api-field__type">null</span></dt><dd>`null` in an error response.</dd></div>
</dl>
```

:::
:::{div} mo-api-split-aside

```{raw} html
<p class="mo-api-example-label">Error response example</p>
```

```json
{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}
```

:::
::::

## Follow-up operations

Record `data.workflow_run.workflow_id` and `data.workflow_run.execution_id`. Acceptance of a request does not mean completion of execution. Use these two identifiers to [query workflow job details](get-workflow-job.md) to track the status; when output is needed, [query workflow job results](get-workflow-job-result.md).