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

# Schedules

> Tools for creating and managing recurring or one-time automated messages

# Schedules

Schedules let your agent set up recurring or one-time automated messages. When a schedule fires, the agent receives a message with the configured text — effectively a self-reminder that can trigger a new session or workflow.

***

## `grid_schedule_create`

Create a recurring or one-time schedule. Describe the schedule in natural language — Grid parses it into cron expressions automatically.

**Parameters:**

| Name           | Type   | Required | Description                                                                 |
| -------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `message_text` | string | Yes      | Message your agent receives when the schedule fires                         |
| `schedule`     | string | Yes      | Natural language schedule (e.g., "every weekday at 9am", "tomorrow at 3pm") |
| `timezone`     | string | No       | Timezone (e.g., `America/New_York`). Defaults to UTC                        |
| `max_fires`    | number | No       | Maximum number of times to fire. Omit for unlimited                         |

```json theme={null}
{
  "message_text": "Check for new support tickets and summarize them",
  "schedule": "every weekday at 9am",
  "timezone": "America/New_York"
}
```

<Callout type="info">
  The `schedule` field supports natural language. Examples: "every Monday at 9am", "every 30 minutes", "tomorrow at 3pm", "every weekday at 8:30am EST".
</Callout>

***

## `grid_schedule_list`

List all schedules — both ones you created and ones created for you by a user on the dashboard.

**Parameters:** None.

Returns each schedule's ID, status, message text, next fire time, and fire count.

***

## `grid_schedule_update`

Update a schedule you created. You can change the schedule, message, status, or max fires.

**Parameters:**

| Name           | Type   | Required | Description                   |
| -------------- | ------ | -------- | ----------------------------- |
| `schedule_id`  | string | Yes      | Schedule UUID                 |
| `schedule`     | string | No       | New natural language schedule |
| `message_text` | string | No       | New message text              |
| `status`       | string | No       | `active` or `paused`          |
| `max_fires`    | number | No       | New maximum number of fires   |

```json theme={null}
{
  "schedule_id": "schedule-uuid",
  "status": "paused"
}
```

<Callout type="info">
  You can only update schedules you created. Schedules created by your owner on the dashboard are read-only.
</Callout>

***

## `grid_schedule_delete`

Delete a schedule you created. This is permanent — the schedule cannot be recovered.

**Parameters:**

| Name          | Type   | Required | Description   |
| ------------- | ------ | -------- | ------------- |
| `schedule_id` | string | Yes      | Schedule UUID |

```json theme={null}
{ "schedule_id": "schedule-uuid" }
```