# Get workflow dispatch job details

<span id="查询工作流派发作业详情"></span>

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

Read the current status and file delivery counts of a workflow batch file dispatch job. `data.dispatch_job.status` reaching `completed` means batch file delivery processing has finished, not that the triggered per-file workflow jobs have completed; continue with [View workflow jobs](list-workflow-jobs.md) to track individual job execution states.

```text
GET https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/{workflow_id}/dispatch-jobs/{dispatch_job_id}
```

<span id="调用前准备"></span>

## Before you begin

1. Prepare a [personal access token](../../../../../guides/genesis/api-keys.md#creating-and-managing-personal-access-tokens) with read permission on the target workflow and the [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-the-workspace-id).
2. Obtain the workflow ID and dispatch job ID from a volume or batch-file run via [Start workflow job](start-workflow-job.md#successful-response), [Retry workflow jobs in batches](../workflow-retries/batch-retry-workflow-jobs.md#successful-response), or [View workflow jobs](list-workflow-jobs.md#successful-response).

<span id="请求参数"></span>

## Request parameters

Replace `$AI_STUDIO_API_KEY`, `$WORKSPACE_ID`, `$WORKFLOW_ID`, and `$DISPATCH_JOB_ID` with actual values.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/dispatch-jobs/$DISPATCH_JOB_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} Parameters

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workflow_id` | string | Yes | Workflow ID that owns the dispatch job. Returns `404` if the dispatch job does not belong to this workflow or workspace. |
| `dispatch_job_id` | string | Yes | Dispatch job ID, obtained from `data.workflow_run.execution_id` when starting a batch-file run, `data.dispatch_job_id` in a batch retry response, or `dispatch_job_id` on a workflow job list item. |

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "dispatch_job": {
      "dispatch_job_id": "dispatch-001",
      "workflow_id": "wf-001",
      "status": "completed",
      "total_deliveries": 12,
      "pending_deliveries": 0,
      "failed_deliveries": 1
    }
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` when the request succeeds. |
| `msg` | string | Response status message. |
| `data` | object | Returned payload for this call. |
| `data.dispatch_job` | object | Dispatch job state and delivery counts. |
| `data.dispatch_job.dispatch_job_id` | string | Dispatch job ID. |
| `data.dispatch_job.workflow_id` | string | Associated workflow ID. |
| `data.dispatch_job.status` | string | Dispatch job status. Possible values: `waiting`, `running`, `completed`, `failed`, `cancelled`. |
| `data.dispatch_job.total_deliveries` | integer | Total number of file deliveries created for this dispatch job. |
| `data.dispatch_job.pending_deliveries` | integer | Number of deliveries still pending, dispatching, or waiting for retry. |
| `data.dispatch_job.failed_deliveries` | integer | Number of deliveries that failed after exhausting retries. |

:::::
::::::
:::::::

<span id="错误响应"></span>

## Error response

An error is returned when the workflow or dispatch job does not exist, the dispatch job does not belong to the specified workflow, or the caller lacks permission to read the workflow. Verify the workspace ID, workflow ID, and dispatch job ID before retrying.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "ErrNotFound",
  "msg": "Not Found"
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code. |
| `msg` | string | Readable error message. |

:::::
::::::
:::::::

### Common HTTP errors

```{list-table}
:header-rows: 1

* - HTTP status
  - Error code
  - Common cause
  - Suggested action
* - 400
  - `ErrParamInvalid`, `ErrWorkspaceRequired`
  - The target workspace header is missing or a path parameter is invalid.
  - Check the workspace header and the workflow ID in the path.
* - 401
  - `Unauthorized`
  - Authentication credentials are missing or invalid.
  - Check that the personal access token is valid.
* - 403
  - `ErrForbidden`
  - The current identity cannot read dispatch jobs for the target workflow.
  - Use an identity with workflow read permission, or request access from an administrator.
* - 404
  - `ErrNotFound`
  - The workflow does not exist or is inactive, or the dispatch job does not belong to the current workspace and specified workflow.
  - Verify `workflow_id`, `dispatch_job_id`, and the target workspace.
* - 500
  - `ErrServer`
  - Failed to read the dispatch record or persisted dispatch state is invalid.
  - Retain the request details and recheck the dispatch status later.
* - 503
  - `ErrServiceUnavailable`
  - Authorization or storage dependencies are temporarily unavailable.
  - Retry the query later.
```
