列出 Schedules

GET /api/v1/forward/schedules 返回 Schedule 配置记录；归档 Schedule 默认不返回。PAT 或管理员 SAT 可省略 identity_id，查询当前 user/workspace owner 下全部 Identity 的 Schedule；Identity-bound SAT 仍只能查询其绑定 Identity。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`

查询参数

参数	类型	是否必填	默认值	说明
identity_id	string	条件必填	-	PAT 或管理员 SAT 可省略，省略时查询当前 owner 全部 Identity；Identity-bound SAT 省略时自动绑定自身，显式传其他 Identity 返回 403。
template_id	string	否	-	按 Forward Template ID 过滤。
status	string	否	-	按 `active` 或 `paused` 过滤。
include_archived	boolean	否	false	是否包含已归档 Schedule。
limit	integer	否	20	分页大小，最大 100。
after_id	string	否	-	向后翻页游标。
before_id	string	否	-	向前翻页游标。
sort_by	string	否	`created_at`	排序字段：`created_at` 或 `upcoming_runs_at`。
order	string	否	`desc`	排序方向：`asc` 或 `desc`。

示例请求

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/schedules?sort_by=upcoming_runs_at&order=desc&limit=20' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

示例响应

HTTP 200 OK

{
  "data": [
    {
      "id": "sched_019f00112233445566778899aabbccdd",
      "identity_id": "idn_019eabc123",
      "template_id": "tmpl_support",
      "name": "Daily tech brief",
      "description": "Generate a daily technology news summary",
      "status": "active",
      "initial_events": [
        {
          "type": "user.message",
          "content": "Summarize current technology news in five bullet points."
        }
      ],
      "execution": {
        "session_mode": "new_session",
        "max_concurrent_runs": 1,
        "max_attempts": 2,
        "timeout_ms": 300000
      },
      "trigger_policy": {
        "type": "cron",
        "expression": "0 9 * * *",
        "timezone": "Asia/Shanghai",
        "upcoming_runs_at": [
          "2026-06-23T01:00:00Z"
        ]
      },
      "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
      "sinks": [
        {
          "type": "im_channel",
          "channel_id": "channel_xxx",
          "target": {
            "type": "user",
            "external_id": "536769"
          }
        }
      ],
      "metadata": {},
      "created_at": "2026-06-22T10:00:00Z",
      "updated_at": "2026-06-22T10:00:00Z"
    }
  ],
  "first_id": "sched_019f00112233445566778899aabbccdd",
  "last_id": "sched_019f00112233445566778899aabbccdd",
  "has_more": false
}

响应字段

字段	类型	说明
data	array	当前页的完整 Schedule 对象。
first_id	string\|null	当前页第一条记录 ID。
last_id	string\|null	当前页最后一条记录 ID。
has_more	boolean	是否还有更多记录。

每个 Schedule 对象的 execution.max_attempts 默认 1，允许值为 1 或 2。2 表示同一个 Schedule Run 在首次执行失败后，最多由服务端自动再尝试一次。是否实际重试以 Schedule Run 的 attempt 字段为准。每个 Schedule 对象的 sinks 响应元素返回 type、channel_id 和 target；target.type 为 user 或 group，并包含 external_id。没有推送目标时返回 []。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	`invalid_identity`	`identity_id` 不合法。
400	`invalid_request_error`	`invalid_request`	`sort_by`、`order` 不合法，同时传入 `after_id` 和 `before_id`，或游标包含不支持的控制字符。
400	`invalid_request_error`	`invalid_limit`	`limit` 不在 1～100 范围内或不是整数。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。
403	`permission_error`	`identity_mismatch`	Identity-bound SAT 显式请求其他 Identity。

备注

默认按 (created_at, schedule_id) 倒序返回；指定 sort_by=upcoming_runs_at 时按下次运行时间和 schedule_id 稳定排序。
upcoming_runs_at 为空的 manual、已到期 once、窗口结束或归档 Schedule 始终排在有下次运行时间的记录之后，不受 order 方向影响。
after_id 与 before_id 不能同时传；游标会按当前 sort_by 和 order 解析，切换排序方式时应重新开始分页。
为保持 v1 兼容性，非空且不含控制字符的 after_id / before_id 如果在当前 owner/Identity 下找不到，服务端会忽略该游标并返回当前筛选与排序条件的第一页。调用方不应依赖该容错，应仅原样回传同一 owner/Identity、sort_by 和 order 下上一页返回的 first_id / last_id。
PAT 或管理员 SAT 显式传入当前 owner 下不存在的 identity_id（包括其他 owner 的 ID）时返回空列表，不泄露该 Identity 是否存在；Identity-bound SAT 的跨 Identity 请求仍返回 403。
归档记录仅在 include_archived=true 时返回。

请求头

查询参数

示例请求

示例响应

响应字段

错误

备注

相关

创建 Schedule

列出 Schedule Runs

​请求头

​查询参数

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

创建 Schedule

列出 Schedule Runs

请求头

查询参数

示例请求

示例响应

响应字段

错误

备注

相关