# 查询工作流派发作业详情

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

查询工作流批量文件派发作业的当前状态和文件投递计数。`data.dispatch_job.status` 变为 `completed` 仅表示批次文件投递处理已结束，不表示各文件触发的工作流作业已执行完成；请继续[查询工作流作业列表](list-workflow-jobs.md)跟踪单个作业的执行状态。

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

## 调用前准备

1. 准备具有目标工作流读取权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。
2. 先通过按卷或批量文件方式[启动工作流作业](start-workflow-job.md#成功响应)、[批量重试工作流作业](../workflow-retries/batch-retry-workflow-jobs.md#成功响应)或[查询工作流作业列表](list-workflow-jobs.md#成功响应)，取得工作流 ID 和派发作业 ID。

## 请求参数

将 `$AI_STUDIO_API_KEY`、`$WORKSPACE_ID`、`$WORKFLOW_ID` 和 `$DISPATCH_JOB_ID` 替换为实际值。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```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} 参数说明

### 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workflow_id` | string | 是 | 派发作业所属的工作流 ID。派发作业不属于该工作流或当前工作区时返回 `404`。 |
| `dispatch_job_id` | string | 是 | 派发作业 ID。可从批量文件启动响应的 `data.workflow_run.execution_id`、批量重试响应的 `data.dispatch_job_id` 或作业列表项的 `dispatch_job_id` 获取。 |

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

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```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} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 请求处理成功时为 `OK`。 |
| `msg` | string | 请求处理的说明文本。 |
| `data` | object | 本次操作返回的数据。 |
| `data.dispatch_job` | object | 派发作业状态与投递统计。 |
| `data.dispatch_job.dispatch_job_id` | string | 派发作业 ID。 |
| `data.dispatch_job.workflow_id` | string | 所属工作流 ID。 |
| `data.dispatch_job.status` | string | 派发作业状态。取值为 `waiting`、`running`、`completed`、`failed`、`cancelled`。 |
| `data.dispatch_job.total_deliveries` | integer | 本次派发作业创建的文件投递总数。 |
| `data.dispatch_job.pending_deliveries` | integer | 仍在等待派发、派发中或等待重试的投递条目数。 |
| `data.dispatch_job.failed_deliveries` | integer | 重试耗尽后投递失败的条目数。 |

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

## 错误响应

目标工作流或派发作业不存在、派发作业不属于指定工作流，或当前凭据无权读取目标工作流时返回错误。核对工作区 ID、工作流 ID 与派发作业 ID 后重试。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码。 |
| `msg` | string | 可读错误信息。 |

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - 400
  - `ErrParamInvalid`、`ErrWorkspaceRequired`
  - 缺少目标工作区或路径参数无效。
  - 检查工作区请求头和路径中的工作流 ID。
* - 401
  - `Unauthorized`
  - 认证凭据缺失或已失效。
  - 检查个人访问令牌是否有效。
* - 403
  - `ErrForbidden`
  - 当前身份无权查看目标工作流的派发作业。
  - 使用具备工作流读取权限的身份，或联系管理员授权。
* - 404
  - `ErrNotFound`
  - 工作流不存在、未激活，或派发作业不属于当前工作区与指定工作流。
  - 核对 `workflow_id`、`dispatch_job_id` 和目标工作区。
* - 500
  - `ErrServer`
  - 服务端读取派发记录失败或持久化派发状态异常。
  - 保留请求标识，稍后核对派发状态。
* - 503
  - `ErrServiceUnavailable`
  - 授权或存储依赖暂不可用。
  - 稍后重试查询。
```
