---
title: "Update schedule"
method: PATCH
path: "/v3/agents/{agent_key}/schedules/{schedule_id}"
tags: ["Agent Schedules"]
---

# Update schedule

`PATCH /v3/agents/{agent_key}/schedules/{schedule_id}`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v3/agents/{agent_key}/schedules/{schedule_id}`
- Auth: HTTP bearer

Partially updates a schedule. Any omitted field is left unchanged. Changing `expression` or `type` (or reactivating from inactive) reschedules the next run and bumps `generation`; payload-only and `agent_tag`-only changes leave the firing cadence in place.

## Path parameters

- `agent_key` string, required: The unique routing key of the agent the schedule belongs to.
- `schedule_id` string, required: The schedule's ULID, as returned from create.

## Request body

- object
  - `agent_tag` string: Change the pinned agent version.
  - `display_name` string: Rename the schedule.
  - `expression` string: Update the schedule expression. Same 6-field cron shapes as create; minimum firing cadence is 1 hour.
  - `is_active` boolean: Activate or deactivate the schedule. Deactivating stops future executions; activating schedules future executions using the current values.
  - `payload` PublicSchedulePayload
    - `input` unknown
    - `memory_entity_id` string: Optional memory store entity ID to attach to each run.
    - `metadata` object: Opaque string key/value pairs attached to every response generated by this schedule.
    - `variables` object: Template variables substituted into instructions. Supports secret values: {"secret": true, "value": "..."}.
  - `type` 'cron': Change the schedule type. Only cron is accepted. Changing the type or expression reschedules future executions and increments generation.

## Response `200`

Schedule updated.

- object
  - `_id` string, required: ULID identifying this schedule.
  - `agent_key` string, required
  - `agent_tag` string: Pinned agent version. Omit to always run the agent's current active version.
  - `created` string, date-time, required
  - `created_by_id` string, required: ID of the API key that created the schedule.
  - `display_name` string: Human-readable name of the schedule. Omitted for schedules created before display names were required.
  - `expression` string, required: 6-field cron expression. Schedules stored before the cron-only restriction may also return an @every duration or an @at RFC3339 timestamp.
  - `generation` integer, required: Monotonic counter incremented when the schedule's firing cadence changes, allowing outdated in-flight triggers to be ignored.
  - `is_active` boolean, required: Whether the schedule is currently firing. Legacy once schedules flip to false automatically after firing.
  - `last_triggered_at` string, date-time: Timestamp of the most recent firing, if any.
  - `payload` PublicSchedulePayload, required
    - `input` unknown
    - `memory_entity_id` string: Optional memory store entity ID to attach to each run.
    - `metadata` object: Opaque string key/value pairs attached to every response generated by this schedule.
    - `variables` object: Template variables substituted into instructions. Supports secret values: {"secret": true, "value": "..."}.
  - `trigger_count` integer, required: Total firings since creation or last expression/type change.
  - `type` 'cron' | 'once' | 'interval', required: Schedule type. Only cron can be created or updated; once and interval only appear on schedules stored before that restriction.
  - `updated` string, date-time, required
  - `updated_by_id` string: ID of the API key that last updated the schedule. Omitted until the schedule is updated.

## Other responses

- `400`: Invalid type, expression, or sub-hour cadence.
- `404`: Schedule or agent version not found.

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)