Scheduled Client
Scheduled client for managing scheduled workflows within Hatchet.
This class provides a high-level interface for creating, deleting, updating, bulk operations, listing, and retrieving scheduled workflow runs.
scheduled = hatchet.scheduled.create(
workflow_name: "my-workflow",
trigger_at: Time.now + 3600,
input: { key: "value" },
additional_metadata: { source: "api" }
)It is available on the main client as hatchet.scheduled.
Methods:
| Name | Description |
|---|---|
create | Create a new scheduled workflow run. |
delete | Delete a scheduled workflow run by its ID. |
update | Reschedule a scheduled workflow run by its ID. |
bulk_delete | Bulk delete scheduled workflow runs. |
bulk_update | Bulk reschedule scheduled workflow runs. |
list | List scheduled workflows based on provided filters. |
get | Retrieve a specific scheduled workflow by ID. |
Functions
create
Create a new scheduled workflow run.
IMPORTANT: It's preferable to use Workflow.run to trigger workflows if possible. This method is intended to be an escape hatch.
scheduled = hatchet.scheduled.create(
workflow_name: "my-workflow",
trigger_at: Time.now + 3600,
input: { key: "value" },
additional_metadata: { source: "api" }
)Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workflow_name | String | The name of the workflow to schedule (namespace will be applied) | required |
trigger_at | Time | The datetime when the run should be triggered. | required |
input | Hash | The input data for the scheduled workflow. | {} |
additional_metadata | Hash | Additional metadata associated with the future run. | {} |
Returns:
| Type | Description |
|---|---|
Object | The created scheduled workflow instance. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
delete
Delete a scheduled workflow run by its ID.
hatchet.scheduled.delete("scheduled-123")Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | String | The ID of the scheduled workflow run to delete. | required |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
update
Reschedule a scheduled workflow run by its ID.
Note: the server may reject rescheduling if the scheduled run has already triggered, or if it was created via code definition (not via API).
hatchet.scheduled.update("scheduled-123", trigger_at: Time.now + 7200)Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | String | The ID of the scheduled workflow run to reschedule. | required |
trigger_at | Time | The new datetime when the run should be triggered. | required |
Returns:
| Type | Description |
|---|---|
Object | The updated scheduled workflow instance. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
bulk_delete
Bulk delete scheduled workflow runs.
Provide either scheduled_ids (explicit list) or one or more filter fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_ids | Array<String> | nil | Explicit list of scheduled workflow run IDs to delete. | nil |
workflow_id | String | nil | Filter by workflow ID. | nil |
parent_workflow_run_id | String | nil | Filter by parent workflow run ID. | nil |
parent_step_run_id | String | nil | Filter by parent step run ID. | nil |
statuses | Array<String> | nil | Filter by scheduled run statuses (warning: may not be supported) | nil |
additional_metadata | Hash | nil | Filter by additional metadata key/value pairs. | nil |
Returns:
| Type | Description |
|---|---|
Object | The bulk delete response containing deleted IDs and per-item errors. |
Raises:
| Type | Description |
|---|---|
ArgumentError | If neither scheduled_ids nor any filter field is provided. |
HatchetSdkRest::ApiError | If the API request fails. |
bulk_update
Bulk reschedule scheduled workflow runs.
hatchet.scheduled.bulk_update([
{ id: "scheduled-1", trigger_at: Time.now + 3600 },
{ id: "scheduled-2", trigger_at: Time.now + 7200 }
])Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
updates | Array<Hash> | Array of hashes with :id and :trigger_at keys. | required |
Returns:
| Type | Description |
|---|---|
Object | The bulk update response containing updated IDs and per-item errors. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
list
List scheduled workflows based on provided filters.
scheduled = hatchet.scheduled.list(limit: 10, workflow_id: "wf-1")Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset | Integer | nil | The offset to use in pagination. | nil |
limit | Integer | nil | The maximum number of scheduled workflows to return. | nil |
workflow_id | String | nil | The ID of the workflow to filter by. | nil |
parent_workflow_run_id | String | nil | The ID of the parent workflow run to filter by. | nil |
statuses | Array<String> | nil | A list of statuses to filter by. | nil |
additional_metadata | Hash | nil | Additional metadata to filter by. | nil |
order_by_field | String | nil | The field to order the results by. | nil |
order_by_direction | String | nil | The direction to order the results by. | nil |
Returns:
| Type | Description |
|---|---|
Object | A list of scheduled workflows matching the provided filters. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
get
Retrieve a specific scheduled workflow by ID.
scheduled = hatchet.scheduled.get("scheduled-123")Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduled_id | String | The scheduled workflow trigger ID to retrieve. | required |
Returns:
| Type | Description |
|---|---|
Object | The requested scheduled workflow instance. |
Raises:
| Type | Description |
|---|---|
HatchetSdkRest::ApiError | If the API request fails. |
Last updated on August 24, 2026