Sign in
Agent Schedules

Update agent schedule

Updates an existing agent schedule. All fields are optional. The update changes only the provided fields (PATCH semantics).

To pause or resume a schedule, set the enabled field to false or true. Updating the schedule configuration (interval or cron) reschedules future executions. Executions currently in progress are not affected.

patch/v2/agents/{agent_key}/schedules/{schedule_key}

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique key of the agent.

schedule_keystring required

A unique key that identifies an agent schedule.

Example:daily-report

The unique key of the schedule to update.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

namestring

The human-readable name of an agent schedule.

descriptionstring

Updated description of the schedule's purpose.

enabledboolean

Updated enabled status for the schedule.

session_metadataobject

Updated metadata to include in each session created by this schedule.

max_executions_to_keepinteger

Updated maximum number of past execution records to keep.

stall_timeout_secondsinteger

Updated number of seconds a scheduled run may go without producing output before it is considered stalled and retried. Omit to leave the current value unchanged.

Example request

{
  "name": "Daily Summary Report",
  "message": [
    {
      "type": "text",
      "content": "I need help with my widget installation",
      "external_id": "1787105665.831929"
    }
  ],
  "schedule": {
    "type": "interval",
    "interval": "PT24H"
  }
}

Response

Updated schedule.

keystring required

A unique key that identifies an agent schedule.

agent_keystring required

A unique key that identifies an agent.

namestring required

The human-readable name of an agent schedule.

descriptionstring

A detailed description of the schedule's purpose.

enabledboolean required

Whether the schedule is currently active and executing.

session_metadataobject

Arbitrary metadata to include in each session created by this schedule.

max_executions_to_keepinteger

Maximum number of past execution records to keep. Older records are deleted automatically when a new execution is recorded.

stall_timeout_secondsinteger

The number of seconds a scheduled run may go without producing output (streamed tokens, tool calls, or other progress events). After this period, the run is considered stalled and is retried. Set this above the longest silent operation the agent performs, so an in-flight run is not retried mid-operation.

last_execution_atstring date-time nullable

Timestamp of the most recent execution. Updated automatically after each execution. Null until the schedule executes for the first time.

created_atstring date-time required

Timestamp when the schedule was created. Create and update responses return the current time. Later reads return 1970-01-01T00:00:00Z.

Example response

{
  "key": "daily-report",
  "agent_key": "customer_support",
  "name": "Daily Summary Report",
  "description": "Generates a daily summary report of customer support activities",
  "message": [
    {
      "type": "text",
      "content": "Generate a summary of today's activities"
    }
  ],
  "schedule": {
    "type": "interval",
    "interval": "PT24H"
  },
  "enabled": true,
  "session_metadata": {
    "report_type": "daily",
    "format": "markdown"
  },
  "max_executions_to_keep": 10,
  "stall_timeout_seconds": 1800,
  "last_execution_at": "2024-01-15T10:30:00Z",
  "created_at": "1970-01-01T00:00:00Z"
}

Changes

Changed in 2 of the 7 revisions of this API.22

  • 0d51a9e3a0b32See the full diff
    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the optional property ////// to the response with the status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 83554494d7f82See the full diff
    • ●

      removed the request property

      request-property-removed

    • ●

      removed the optional property from the response with the status

      response-optional-property-removed