Skip to main content
The Scheduler Blob Type stores a collection of schedules that trigger workflow executions on a time-based cadence. Each schedule retains a history of its past executions.

​
Alias Grammar

A schedule may carry an optional alias — a short, stable name usable anywhere the schedule’s id is accepted. The 6-character floor rejects the names most people try first: main, dev, prod and ci are all too short and are refused. primary, default, staging, daily_report and nightly-build all clear it. The alias is optional — a schedule without one simply omits alias from responses, rather than carrying it as null. The grammar is enforced when an alias is set — at create and at rename. Reads normalize case and surrounding whitespace before resolving, so a lookup does not have to match the stored value byte-for-byte. A schedule’s own alias is not the only “alias” in view here. It sits in the same payload as invocation_target.workflow_alias, and create_execution takes a separate alias parameter meaning the workflow definition’s alias. When a schedule’s alias and its invocation_target.workflow_alias appear side by side — as they do on every schedule response — they name two different things: the schedule itself, and the workflow it invokes when it fires. Read alias at the top level of a schedule as the schedule’s own name; read workflow_alias inside invocation_target as the target it runs. Workflow sessions support the same optional alias, with the same grammar. get_session, update_session, close_session, reopen_session, delete_session, get_schedule, update_schedule and delete_schedule all accept an id or an alias in their session_id / schedule_id parameter — every command that addresses the object itself. Everything else is id only, including create_execution, list_executions, list_session_events, and every session-object, thread and graph command: these address content inside a session or schedule rather than the object itself, so a caller resolves the alias once — on the command that returns the object — and holds the id from there on. This is the session’s or schedule’s own alias, not to be confused with a session object’s alias — the path-style name given to individual objects stored inside a session, documented in Session Objects. The two grammars are deliberately incompatible: that one allows slashes, dots and uppercase that this one forbids, so a value valid under one can never be mistaken for the other. Alias resolution reads a secondary index and is eventually consistent: creating an object with an alias and immediately addressing it by that alias can fail briefly. Hold the id the create call returns rather than re-resolving by alias on every call.

​
Schedule Types

A schedule fires either once or on a recurring cadence. The repeat field controls which:
  • one_time — fires once at a specified invocation_time. After firing, the schedule transitions to the completed state.
  • recurring_cron — fires repeatedly based on a cron_expression. Stays active until deleted, or until end_date is reached (if provided).

​
Cron Expressions

Recurring schedules use the AWS EventBridge Scheduler six-field cron format:
Only the inner six fields are stored in cron_expression. A few common examples: Either day-of-month or day-of-week must be ? (AWS cron does not allow both to be specified).

​
Timezones

Every schedule requires an IANA timezone string in the timezone field (for example, America/New_York, Europe/London, or UTC). Both cron expressions and one-time invocation times are evaluated in this timezone.

​
Date Windowing

Schedules accept optional start_date and end_date fields (ISO 8601, UTC) that constrain when the schedule is active:
  • Before start_date, the schedule does not fire.
  • After end_date, the schedule does not fire. A recurring schedule automatically transitions to the completed state once end_date is passed.
Both fields are optional and may be omitted.

​
Invocation Targets

A schedule invokes a target each time it fires. The currently supported target type is workflow, which creates a workflow execution on a target blob revision. The invocation_target object has the following fields:
org_id and blob_id for the target blob are derived by the server from revision_id. They appear on the persisted schedule and in all responses, but they must not be supplied in create_schedule or update_schedule request bodies.

​
Authorization

Schedules execute on behalf of the auth entity (user or organization) that created them. At the time of invocation, that auth entity must still have access to the target blob. If access has been revoked, the execution fails with invocation_error and no workflow is started.

​
Execution History

Every time a schedule fires it creates an execution record. Executions are fire-and-forget: the execution result captures the immediate outcome of creating the workflow execution, not the final outcome of the workflow itself. Each execution has a status field with one of two values:

​
Schedule States

A schedule is always in one of two states, stored in its state field:
  • active — the schedule can be updated or deleted. One-time schedules remain active until they fire; recurring schedules remain active indefinitely or until their end_date is reached.
  • completed — the schedule is read-only. Completed schedules cannot be updated but can still be deleted.