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

```ruby
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.

```ruby
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.

```ruby
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).

```ruby
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 \, 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 \, 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.

```ruby
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`, 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.

```ruby
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 \, 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.

```ruby
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.