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

# 查询工作流执行进度

> 查询工作流运行的实时进度、日志和输出结果

# 查询工作流执行进度

根据运行订单 ID 查询执行引擎侧的任务状态、队列信息、实时进度、运行日志和输出结果。前端轮询时建议使用此接口。

## 请求参数

<ParamField query="run_order_id" type="string" required>
  运行订单 ID
</ParamField>

## 响应参数

<ResponseField name="code" type="integer">
  响应码，`0` 表示成功
</ResponseField>

<ResponseField name="msg" type="string">
  响应信息
</ResponseField>

<ResponseField name="data" type="object">
  执行任务详情

  <Expandable title="data">
    <ResponseField name="task_id" type="string">
      执行引擎任务 ID
    </ResponseField>

    <ResponseField name="workflow_id" type="string">
      工作流 ID
    </ResponseField>

    <ResponseField name="status" type="string">
      执行状态，如 `queued`、`running`、`succeeded`、`failed`
    </ResponseField>

    <ResponseField name="queue_info" type="object">
      队列信息。排队时包含 `position` 和 `estimated_wait_sec`
    </ResponseField>

    <ResponseField name="progress_percent" type="integer">
      执行进度百分比
    </ResponseField>

    <ResponseField name="progress_snapshot" type="object">
      执行引擎进度快照
    </ResponseField>

    <ResponseField name="logs" type="array">
      运行日志列表。日志项包含 `at`、`event_type`、`level`、`message`、`node_id`、`progress_percent`
    </ResponseField>

    <ResponseField name="actual_execution_duration_sec" type="number">
      实际执行时长，单位秒
    </ResponseField>

    <ResponseField name="compute_cost" type="number">
      计算资源费用
    </ResponseField>

    <ResponseField name="external_model_cost" type="number">
      第三方模型费用
    </ResponseField>

    <ResponseField name="total_cost" type="number">
      实际总消耗
    </ResponseField>

    <ResponseField name="outputs" type="object">
      输出结果。key 来自详情接口的 `candidate_output_manifest`，值可能是文本、图片、视频或音频地址
    </ResponseField>

    <ResponseField name="error" type="object">
      失败信息，成功时为 `null`
    </ResponseField>

    <ResponseField name="created_at" type="string">
      创建时间
    </ResponseField>

    <ResponseField name="started_at" type="string">
      开始执行时间
    </ResponseField>

    <ResponseField name="terminal_at" type="string">
      终态时间
    </ResponseField>
  </Expandable>
</ResponseField>

## 错误响应

当查询执行进度时执行引擎暂不可用或返回错误，接口会返回一个简单原因和详细错误信息。

<ResponseField name="code" type="integer">
  非 `0` 表示失败
</ResponseField>

<ResponseField name="msg" type="string">
  简单失败原因
</ResponseField>

<ResponseField name="data.error" type="object">
  执行引擎错误详情

  <Expandable title="data.error">
    <ResponseField name="reason" type="string">
      简单失败原因，与 `msg` 保持一致
    </ResponseField>

    <ResponseField name="detail" type="string">
      详细错误信息
    </ResponseField>

    <ResponseField name="engine_code" type="string">
      执行引擎返回的错误码
    </ResponseField>

    <ResponseField name="status_code" type="integer">
      执行引擎 HTTP 状态码
    </ResponseField>
  </Expandable>
</ResponseField>

## 代码示例

<CodeGroup>
  ```python Python theme={null}
  import time
  import requests

  url = "https://www.chenyu.cn/api/open/v2/workflow/run/execution"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }
  params = {
      "run_order_id": "wfrun_314ff7d8b7a5beff1388"
  }

  while True:
      result = requests.get(url, headers=headers, params=params).json()
      task = result["data"]
      print(task["status"], task.get("progress_percent"))

      if task["status"] in ["succeeded", "failed", "canceled"]:
          print(task.get("outputs"))
          break

      time.sleep(2)
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  async function pollExecution(runOrderId) {
    const response = await axios.get('https://www.chenyu.cn/api/open/v2/workflow/run/execution', {
      headers: {
        Authorization: 'Bearer your_api_key',
        'Content-Type': 'application/json'
      },
      params: {
        run_order_id: runOrderId
      }
    });

    const task = response.data.data;
    console.log(task.status, task.progress_percent, task.logs);
    return task;
  }

  pollExecution('wfrun_314ff7d8b7a5beff1388');
  ```

  ```curl cURL theme={null}
  curl -X GET "https://www.chenyu.cn/api/open/v2/workflow/run/execution?run_order_id=wfrun_314ff7d8b7a5beff1388" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## 响应示例

```json theme={null}
{
  "code": 0,
  "msg": "查询成功",
  "data": {
    "task_id": "task_1778147626528703038_eb84d292e0851c08",
    "workflow_id": "wf_861ef31e94dcfb10e6e7",
    "status": "succeeded",
    "queue_info": null,
    "progress_percent": 100,
    "progress_snapshot": {
      "internal_status": "succeeded",
      "completed_node_count": 7,
      "total_runnable_nodes": 7,
      "last_event_type": "execution_success"
    },
    "logs": [
      {
        "at": "2026-05-08T10:00:01Z",
        "event_type": "execution_start",
        "level": "info",
        "message": "execution started",
        "progress_percent": 0
      },
      {
        "at": "2026-05-08T10:00:10Z",
        "event_type": "execution_success",
        "level": "info",
        "message": "execution succeeded",
        "progress_percent": 100
      }
    ],
    "actual_execution_duration_sec": 8.42,
    "compute_cost": 0.0002878,
    "external_model_cost": 0,
    "total_cost": 0.0002878,
    "outputs": {
      "n9_images": "https://www.chenyu.cn/media/example-output"
    },
    "error": null,
    "created_at": "2026-05-08T10:00:00Z",
    "started_at": "2026-05-08T10:00:01Z",
    "terminal_at": "2026-05-08T10:00:10Z"
  }
}
```

## 错误示例

```json theme={null}
{
  "code": 1,
  "msg": "Task not found.",
  "data": {
    "error": {
      "reason": "Task not found.",
      "detail": "execution task task_1778147626528703038_eb84d292e0851c08 does not exist",
      "engine_code": "TASK_NOT_FOUND",
      "status_code": 404
    }
  }
}
```