# 查询 Deployment Run 列表

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`GET https://ark.cn-beijing.volces.com/api/v3/deployment_runs`

查询全部 Deployment 的运行记录，用于跟踪定时任务每次触发的启动情况。

Run 记录只表示 Session 启动结果，不表示 Agent 任务的最终执行结果。列表按创建时间倒序排列。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### Query 参数

> 在 URL Query String 中传入。

**created_at_gt** `string` | 创建时间下界

只返回创建时间严格大于该值的 Run，采用 RFC 3339 格式。不能与 `created_at_gte` 同时使用。

**created_at_gte** `string` | 创建时间下界

只返回创建时间大于或等于该值的 Run，采用 RFC 3339 格式。不能与 `created_at_gt` 同时使用。

**created_at_lt** `string` | 创建时间上界

只返回创建时间严格小于该值的 Run，采用 RFC 3339 格式。不能与 `created_at_lte` 同时使用。

**created_at_lte** `string` | 创建时间上界

只返回创建时间小于或等于该值的 Run，采用 RFC 3339 格式。不能与 `created_at_lt` 同时使用。

**deployment_id** `string` | Deployment ID

按 Deployment ID 精确筛选。

**has_error** `boolean` | 是否失败

`true` 只返回启动失败的记录，`false` 只返回启动成功的记录；省略时返回全部记录。

**limit** `integer` `默认值 20` | 每页数量

每页返回的最大记录数。

**取值范围**：`[1, 1000]`

**page** `string` | 下一页标识

首次查询时省略；继续查询时，将上一页响应返回的 `next_page` 原样传入，不要解析、修改或自行生成。最后一页不再返回 `next_page`，此时停止翻页。

**trigger_type** `string` | 触发类型

按触发来源筛选。可选值：`manual`、`schedule`。

## 响应参数

**data** `object[]` | Run 列表

当前页的 Deployment Run 对象列表。

**agent** `object` | Agent 引用

`data.agent`

本次 Run 受理时固定的 Agent 和版本。

**id** `string` | Agent ID

`data.agent.id`

Deployment 使用的 Agent ID。

**type** `string` | 对象类型

`data.agent.type`

Agent 引用类型，固定为 `agent`。

**version** `integer` | Agent 版本

`data.agent.version`

Deployment 固定使用的 Agent 版本号。

**created_at** `string` | 创建时间

`data.created_at`

Run 记录创建时间，采用 RFC 3339 格式。

**deployment_id** `string` | Deployment ID

`data.deployment_id`

触发本次 Run 的 Deployment ID。

**id** `string` | Run ID

`data.id`

Deployment Run 的唯一标识符，以 `drun-` 开头，形如 `drun-<14位时间戳>-<10位随机字符>`。

**trigger_context** `object` | 触发上下文

`data.trigger_context`

本次 Run 的触发来源和计划时间。

**type** `string` | 触发类型

`data.trigger_context.type`

触发类型。`manual` 表示调用立即运行接口；`schedule` 表示定时计划触发。

**scheduled_at** `string` | 计划时间

`data.trigger_context.scheduled_at`

定时 Run 的理论计划时间，采用 RFC 3339 格式，不包含调度抖动。手动 Run 不返回该字段。

**type** `string` | 对象类型

`data.type`

对象类型，固定为 `deployment_run`。

**error** `object` | 失败信息

`data.error`

Run 启动失败时返回的错误信息。Run 成功或尚未结束时不返回该字段。

**message** `string` | 错误信息

`data.error.message`

用于定位失败原因的可读信息。

**type** `string` | 错误类型

`data.error.type`

错误分类。

**session_id** `string` | Session ID

`data.session_id`

Session 和初始事件均受理成功时返回的 Session ID。Run 失败或尚未结束时不返回该字段。

**next_page** `string` | 下一页标识

还有更多结果时返回。继续查询时，将该值原样传入 `page`，不要解析、修改或自行生成；最后一页不返回该字段。


## 代码示例

## 查询 Deployment Run 列表

### cURL


#### Request

```bash
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/deployment_runs?deployment_id=$DEPLOYMENT_ID&limit=2" \
  -H "Authorization: Bearer $ARK_API_KEY"
```

#### Response

```
{
  "data": [
    {
      "type": "deployment_run",
      "id": "drun-20261021090000-m1n2o",
      "deployment_id": "depl-20261020090000-a1b2c",
      "agent": {
        "type": "agent",
        "id": "agent-20261018090000-a1b2c",
        "version": 3
      },
      "created_at": "2026-10-21T01:00:05Z",
      "trigger_context": {
        "type": "schedule",
        "scheduled_at": "2026-10-21T01:00:00Z"
      },
      "error": {
        "type": "session_create_error",
        "message": "deployment run drun-20261021090000-m1n2o failed during session_create_error"
      }
    },
    {
      "type": "deployment_run",
      "id": "drun-20261020093000-f6g7h",
      "deployment_id": "depl-20261020090000-a1b2c",
      "agent": {
        "type": "agent",
        "id": "agent-20261018090000-a1b2c",
        "version": 3
      },
      "created_at": "2026-10-20T01:30:00Z",
      "trigger_context": {
        "type": "manual"
      },
      "session_id": "sesn-20261020093000-j8k9l"
    }
  ]
}
```