> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Understanding the Scheduler blob type.

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.

| Rule       | Value                                                   |
| :--------- | :------------------------------------------------------ |
| Characters | `a`–`z`, `0`–`9`, `_`, `-`                              |
| Length     | 6–42 characters                                         |
| Case       | lowercase only                                          |
| Uniqueness | within the revision, among schedules that have an alias |

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](/blob-types/workflow/session-objects/introduction#alias-grammar-the-namespace).
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:

```
cron(minutes hours day-of-month month day-of-week year)
```

Only the inner six fields are stored in `cron_expression`. A few common examples:

| Expression          | Meaning                |
| :------------------ | :--------------------- |
| `0 9 * * ? *`       | Every day at 09:00     |
| `0 * * * ? *`       | Every hour at minute 0 |
| `0 9 ? * MON-FRI *` | Every weekday at 09:00 |
| `*/15 * * * ? *`    | Every 15 minutes       |

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:

| Field            | Type   | Required | Description                                                    |
| :--------------- | :----- | :------- | :------------------------------------------------------------- |
| `revision_id`    | string | Yes      | Target workflow blob revision id.                              |
| `session_id`     | string | Yes      | Session id under which the workflow execution will be created. |
| `workflow_alias` | string | Yes      | Alias of the workflow definition to execute.                   |
| `input_data`     | array  | Yes      | Input data array passed to the workflow execution.             |
| `description`    | string | No       | Optional execution description (max 256 characters).           |

<Note>
  `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.
</Note>

## 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:

| Status             | Meaning                                                                                                                                   |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `success`          | The target workflow execution was created successfully.                                                                                   |
| `invocation_error` | The target could not be invoked — for example, the schedule's auth entity has lost access to the target, or the target itself is invalid. |

## 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.