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

## 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 `access_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 three values:

| Status             | Meaning                                                        |
| :----------------- | :------------------------------------------------------------- |
| `success`          | The target workflow execution was created successfully.        |
| `access_error`     | The schedule's auth entity no longer has access to the target. |
| `invocation_error` | The target could not be invoked for another reason.            |

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