# 查询 Deployment 列表

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

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

查询当前账号和项目下的全部 Deployment，用于浏览和维护定时任务。

列表按创建时间倒序排列；列表较长时，将上一次响应中的 `next_page` 原样传入即可翻页。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [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 中传入。

**agent_id** `string` | Agent ID

按 Agent ID 精确筛选。

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

只返回创建时间大于或等于该值的 Deployment，采用 RFC 3339 格式。

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

只返回创建时间小于或等于该值的 Deployment，采用 RFC 3339 格式。

**include_archived** `boolean` `默认值 false` | 包含归档项

是否包含已归档的 Deployment。

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

每页返回的最大记录数。

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

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

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

**search** `string` | 搜索内容

传完整 Deployment ID 时按 ID 精确匹配；其他值按名称模糊匹配。

**status** `string` | 运行状态

按运行状态筛选。仅支持 `active` 和 `paused`，传其他值返回 400 错误。归档项是否进入结果由 `include_archived` 单独控制。

## 响应参数

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

当前页的 Deployment 对象列表。

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

`data.agent`

Deployment 固定使用的 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`

Deployment 创建时间，采用 RFC 3339 格式。

**environment_id** `string` | Environment ID

`data.environment_id`

每次运行使用的 Environment ID。

**id** `string` | Deployment ID

`data.id`

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

**initial_events** `object[]` | 初始事件

`data.initial_events`

每次运行创建新 Session 后发送的启动事件模板。

用户消息 `object`

用户消息事件。每次运行创建 Session 后，平台会把该消息作为启动任务的第一条用户输入发送给 Agent。

**content** `object[]` | 消息内容

`data.initial_events.content`

消息内容块列表。支持文本、图片、文档和视频，字段结构与发送会话事件接口中的 `user.message` 一致；详情请参见 [会话事件结构参考](/docs/sessions-events-reference-v2)。

**type** `string` | 内容类型

`data.initial_events.content.type`

内容块类型。完整结构请参见 [会话事件结构参考](/docs/sessions-events-reference-v2)。可选值：`text`、`image`、`document`、`video`。

**type** `string` | 事件类型

`data.initial_events.type`

事件类型，固定为 `user.message`。

**name** `string` | 名称

`data.name`

Deployment 名称。

**resources** `object[]` | 挂载资源

`data.resources`

每次运行创建 Session 时使用的资源配置。

**type** `string` | 资源类型

`data.resources.type`

资源类型。`file` 表示通过 Files API 上传并挂载到 Session 的文件；`memory_store` 表示挂载到 Session 的记忆库；`tos` 表示挂载到 Session 的 TOS 对象目录。

**access** `string` | 访问权限

`data.resources.access`

每次运行创建的 Session 对该资源的访问权限。`read_only` 表示智能体只能读取资源；`read_write` 表示智能体可以读取和修改支持写入的资源。

**file_id** `string` | 文件 ID

`data.resources.file_id`

当 *type* 为 `file` 时，表示要挂载到 Session 的文件 ID，通过 Files API 上传文件后获得。

**memory_store_id** `string` | 记忆库 ID

`data.resources.memory_store_id`

当 *type* 为 `memory_store` 时，表示要挂载到 Session 的记忆库 ID。

**mount_path** `string` | 挂载路径

`data.resources.mount_path`

该资源在每次运行创建的 Session 运行环境中的挂载路径。

**tos_bucket** `string` | TOS 存储桶

`data.resources.tos_bucket`

当 *type* 为 `tos` 时，表示待挂载目录所在的 TOS 存储桶名称。

**tos_key** `string` | TOS 目录前缀

`data.resources.tos_key`

当 *type* 为 `tos` 时，表示 TOS 中待挂载目录的对象前缀。前缀必须以 `/` 结尾。

**tos_region** `string` | TOS 地域

`data.resources.tos_region`

当 *type* 为 `tos` 时，表示源存储桶所在地域的 Region ID。

**status** `string` | 运行状态

`data.status`

Deployment 的调度状态。`paused` 不接受定时触发，但仍允许手动运行；`archived_at` 有值时已归档，无论该字段取值如何都不再接受任何触发。取值：`active` / `paused`。

**tags** `object[]` | 标签

`data.tags`

Deployment 标签列表。

**key** `string` | 标签键

`data.tags.key`

标签键，用于标识分类维度。

**value** `string` | 标签值

`data.tags.value`

标签值，用于记录该分类维度的具体内容。

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

`data.type`

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

**updated_at** `string` | 更新时间

`data.updated_at`

Deployment 最近更新时间，采用 RFC 3339 格式。

**vault_ids** `string[]` | 保管库 ID

`data.vault_ids`

每次运行创建 Session 时绑定的 Vault ID 列表。

**archived_at** `string` | 归档时间

`data.archived_at`

Deployment 归档时间，采用 RFC 3339 格式。未归档时不返回该字段。

**description** `string` | 描述

`data.description`

Deployment 描述。未设置时不返回该字段。

**paused_reason** `object` | 暂停原因

`data.paused_reason`

Deployment 暂停的原因。*status* 为 `active` 时不返回该字段。

**type** `string` | 暂停类型

`data.paused_reason.type`

暂停原因类型。`manual` 表示调用暂停接口；`error` 表示 Run 遇到不可恢复错误后自动暂停。

**error** `object` | 暂停错误

`data.paused_reason.error`

自动暂停时的错误信息。*type* 为 `manual` 时不返回该字段。

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

`data.paused_reason.error.message`

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

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

`data.paused_reason.error.type`

错误分类。

**schedule** `object` | 定时计划

`data.schedule`

定时触发计划。仅支持手动运行时不返回该字段。

**expression** `string` | Cron 表达式

`data.schedule.expression`

五段式 cron 表达式，格式为 `分钟 小时 日期 月份 星期`。例如 `0 9 * * 1-5` 表示在配置时区的工作日 09:00 触发；不支持秒、年份和 `@daily` 等快捷写法。

**timezone** `string` | 时区

`data.schedule.timezone`

cron 表达式使用的 IANA 时区，例如 `Asia/Shanghai`、`UTC` 或 `America/New_York`。平台按该时区计算计划触发时间。

**type** `string` | 计划类型

`data.schedule.type`

计划类型，固定为 `cron`。

**upcoming_runs_at** `string[]` | 后续计划时间

`data.schedule.upcoming_runs_at`

接下来最多 5 个理论计划时间，采用 RFC 3339 格式，不包含调度抖动。Deployment 暂停时仍返回按当前计划计算的时间；归档后返回空数组。

**last_run_at** `string` | 最近定时运行时间

`data.schedule.last_run_at`

最近一次定时 Run 的理论计划时间，采用 RFC 3339 格式。尚未定时触发时不返回该字段；手动 Run 不更新该字段。

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

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


## 代码示例

## 查询 Deployment 列表

### cURL


#### Request

```bash
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/deployments?status=active&limit=1" \
  -H "Authorization: Bearer $ARK_API_KEY"
```

#### Response

```
{
  "data": [
    {
      "type": "deployment",
      "id": "depl-20261020090000-a1b2c",
      "name": "工作日业务日报",
      "description": "汇总昨日业务数据并生成日报",
      "agent": {
        "type": "agent",
        "id": "agent-20261018090000-a1b2c",
        "version": 3
      },
      "environment_id": "env-20261018090500-d3e4f",
      "initial_events": [
        {
          "type": "user.message",
          "content": [
            {
              "type": "text",
              "text": "分析昨日业务数据，生成日报并列出异常指标。"
            }
          ]
        }
      ],
      "schedule": {
        "type": "cron",
        "expression": "0 9 * * 1-5",
        "timezone": "Asia/Shanghai",
        "upcoming_runs_at": [
          "2026-10-21T01:00:00Z",
          "2026-10-22T01:00:00Z"
        ]
      },
      "status": "active",
      "resources": [],
      "vault_ids": [],
      "tags": [
        {
          "key": "business",
          "value": "daily-report"
        }
      ],
      "created_at": "2026-10-20T01:00:00Z",
      "updated_at": "2026-10-20T01:00:00Z"
    }
  ],
  "next_page": "MTc2MDkyMjAwMDAwMDAwMDpkZXBsLTEwMDE"
}
```