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

# 获取 Schedule Run

> 根据 ID 获取一条 Schedule Run。

`GET /api/v1/forward/schedule_runs/{run_id}`

返回单条 Schedule Run 执行记录。可传 `identity_id` 作为额外归属约束。

## 请求头

| Header        | 是否必填 | 说明             |
| ------------- | ---- | -------------- |
| Authorization | 是    | `Bearer <PAT>` |

## 路径参数

| 参数      | 类型     | 是否必填 | 说明               |
| ------- | ------ | ---- | ---------------- |
| run\_id | string | 是    | Schedule Run ID。 |

## 查询参数

| 参数           | 类型     | 是否必填 | 默认值 | 说明      |
| ------------ | ------ | ---- | --- | ------- |
| identity\_id | string | 否    | -   | 额外归属约束。 |

## 示例请求

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/schedule_runs/srun_019f00112233445566778899aabbccdd' \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "id": "srun_019f00112233445566778899aabbccdd",
  "schedule_id": "sched_019f00112233445566778899aabbccdd",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "session_id": "sess_019ec55a68b37e1e8d660691af161ab4",
  "status": "completed",
  "trigger_context": {
    "type": "schedule",
    "scheduled_at": "2026-06-22T01:00:00Z"
  },
  "result_payload": "Today's technology highlights: ...",
  "push_sink": "im_channel",
  "push_status": "succeeded",
  "push_finished_at": "2026-06-22T01:00:21Z",
  "attempt": 1,
  "triggered_at": "2026-06-22T01:00:00Z",
  "started_at": "2026-06-22T01:00:03Z",
  "completed_at": "2026-06-22T01:00:20Z",
  "duration_ms": 17000,
  "created_at": "2026-06-22T01:00:00Z"
}
```

## 响应字段

| 字段                 | 类型              | 说明                                                                 |
| ------------------ | --------------- | ------------------------------------------------------------------ |
| id                 | string          | Schedule Run ID。                                                   |
| schedule\_id       | string          | 所属 Schedule ID。                                                    |
| identity\_id       | string          | Forward Identity ID。                                               |
| template\_id       | string          | Forward Template ID。                                               |
| session\_id        | string \| null  | 本次执行创建或使用的 Session。                                                |
| status             | string          | `pending`、`running`、`completed`、`failed` 或 `skipped`。              |
| trigger\_context   | object          | 触发来源。                                                              |
| error              | object \| null  | 失败或跳过时的结构化错误。                                                      |
| result\_payload    | string \| null  | 主流程文本结果。                                                           |
| error\_message     | string \| null  | 便于展示的错误信息；结构化信息保留在 `error`。                                        |
| push\_sink         | string \| null  | 本次 IM 投递使用的 Sink 类型；未配置投递时为 `null`。                                |
| push\_status       | string          | IM 投递状态：`pending`、`succeeded`、`failed` 或 `skipped`。主流程状态与投递状态相互独立。 |
| push\_finished\_at | string \| null  | IM 投递结束时间。                                                         |
| attempt            | integer         | 尝试序号，当前为 `1`。                                                      |
| triggered\_at      | string          | 触发时间。                                                              |
| started\_at        | string \| null  | 开始执行时间。                                                            |
| completed\_at      | string \| null  | 结束时间。                                                              |
| duration\_ms       | integer \| null | 执行耗时，单位毫秒。                                                         |
| created\_at        | string          | 记录创建时间。                                                            |

## Trigger Context 对象

| type       | 说明                                                                                        |
| ---------- | ----------------------------------------------------------------------------------------- |
| `schedule` | 系统根据 Schedule 的 `trigger_policy` 自动触发，例如 `cron`、`once`、`interval`；自动触发时返回 `scheduled_at`。 |
| `manual`   | 调用 `POST /api/v1/forward/schedules/{schedule_id}/run` 手动触发。                               |

## Run Error 对象

`error` 对象用于表达结构化失败或跳过原因。`status=failed` 或 `status=skipped` 时可能返回；`status=completed` 时为 `null`。

| error.type                  | 说明                                                             |
| --------------------------- | -------------------------------------------------------------- |
| `concurrency_limit_reached` | 同一个 Schedule 已达到 `execution.max_concurrent_runs`，本次触发已记录但不会执行。 |
| `session_creation_failed`   | 创建或绑定 Forward Session 失败。                                      |
| `execution_failed`          | Template 执行失败。                                                 |

## 错误

| HTTP | Type                   | Code                      | 触发条件                               |
| ---- | ---------------------- | ------------------------- | ---------------------------------- |
| 404  | `not_found_error`      | `schedule_run_not_found`  | Run 不存在、跨租户，或不满足 `identity_id` 约束。 |
| 401  | `authentication_error` | `authentication_required` | PAT 无效或已过期。                        |

## 注意事项

* `error.type=concurrency_limit_reached` 表示已记录本次触发，但因并发限制被跳过。
* 可轮询本接口直到 `status` 进入终态。

## 相关

<CardGroup cols={2}>
  <Card title="列出 Schedule Runs" icon="history" href="/cloud-agents/api/forward/schedule-runs/list" />

  <Card title="获取 Schedule" icon="file-lines" href="/cloud-agents/api/forward/schedules/get" />
</CardGroup>