List schedules

GET /api/v1/forward/schedules Returns Schedule configuration records. Archived schedules are excluded by default. PATs and administrator SATs may omit identity_id to query all Identities under the current user or workspace owner. Identity-bound SATs remain restricted to their bound Identity.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`

Query parameters

Parameter	Type	Required	Default	Description
`identity_id`	string	Conditional	-	PATs and administrator SATs may omit it to query all Identities under the current owner. An Identity-bound SAT defaults to its bound Identity and receives 403 if it explicitly requests another Identity.
`template_id`	string	No	-	Filter by Forward Template ID.
`status`	string	No	-	Filter by `active` or `paused`.
`include_archived`	boolean	No	`false`	Include archived schedules.
`limit`	integer	No	20	Items per page. Maximum 100.
`after_id`	string	No	-	Cursor for records after the given Schedule ID.
`before_id`	string	No	-	Cursor for records before the given Schedule ID.
`sort_by`	string	No	`created_at`	Sort field: `created_at` or `upcoming_runs_at`.
`order`	string	No	`desc`	Sort direction: `asc` or `desc`.

Example request

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"

Example response

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
}

Response fields

Field	Type	Description
`data`	array	Full Schedule objects on the current page.
`first_id`	string\|null	ID of the first record on this page.
`last_id`	string\|null	ID of the last record on this page.
`has_more`	boolean	Whether more records remain.

Each Schedule object's execution.max_attempts defaults to 1, allowed values are 1 or 2. A value of 2 means the server may automatically retry once after the first execution fails. Whether a retry actually occurred is determined by the attempt field on Schedule Run objects. Each Schedule object's sinks response elements return type, channel_id, and target; target.type is user or group and includes external_id. When there is no delivery target, the response returns [].

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_identity`	`identity_id` is invalid.
400	`invalid_request_error`	`invalid_request`	`sort_by` or `order` is invalid, both `after_id` and `before_id` are supplied, or a cursor contains unsupported control characters.
400	`invalid_request_error`	`invalid_limit`	`limit` is not an integer from 1 through 100.
401	`authentication_error`	`authentication_required`	PAT or SAT invalid or expired.
403	`permission_error`	`identity_mismatch`	An Identity-bound SAT explicitly requests another Identity.

Notes

By default, results are sorted by (created_at, schedule_id) in descending order. With sort_by=upcoming_runs_at, results use the next run time and schedule_id as a stable sort key.
Schedules without a next run time—including manual, expired once, window-ended, and archived schedules—always follow schedules that have a next run time, regardless of order.
Do not supply after_id and before_id together. Cursors are interpreted under the current sort_by and order; restart pagination when changing the sort.
For v1 compatibility, a non-empty cursor without control characters that cannot be found under the current owner or Identity is ignored and the first page for the current filters and sort is returned. Do not depend on this fallback. Replay only first_id or last_id returned for the same owner or Identity, sort_by, and order.
If a PAT or administrator SAT specifies an identity_id that is not under the current owner, the API returns an empty list without revealing whether the Identity exists. Cross-Identity requests from an Identity-bound SAT still return 403.
Archived records are returned only when include_archived=true.

Headers

Query parameters

Example request

Example response

Response fields

Errors

Notes

Create a schedule

List schedule runs

​Headers

​Query parameters

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

Create a schedule

List schedule runs

Headers

Query parameters

Example request

Example response

Response fields

Errors

Notes

Related