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

# Overview

Use the Schedules API to run saved queries and refresh dashboards on a schedule, from code or from an AI agent. List the schedules you can see, set a schedule on a query or a dashboard, and delete it. These are the same schedules you set in the [query scheduler](https://docs.dune.com/web-app/query-editor/query-scheduler.md) in the Dune app, so a change made through the API appears in the app right away.

The same operations are available as tools in the [Dune MCP server](https://docs.dune.com/docs/agents/mcp.md).

## Use Cases

* **AI Agents**: Let an agent keep the queries and dashboards it builds fresh, without a manual step in the app.
* **Fresh Results for Apps**: Run a query on a schedule, then read its latest result with [Get Latest Query Result](https://docs.dune.com/api-reference/executions/endpoint/get-query-result.md).
* **Bulk Changes**: Move many schedules to a lower frequency or a smaller performance tier in one script.
* **Cleanup**: Find and delete schedules you no longer need, to stop their credit use.

## Behavior

* A query or a dashboard has at most one schedule. You address it by the query ID or the dashboard ID.
* `PUT` creates the schedule, or replaces all the settings of the one that exists. Send every setting you want to keep. An omitted `expires_at` means no expiry date.
* Every scheduled run costs credits at the chosen performance tier: `small`, `medium`, or `large`. The tier must be available to the API on the owner's plan.
* The schedule belongs to the owner of the query or dashboard. You must own it, or be an editor or admin of the team that owns it. A team API key can only change its own team's content.
* The owner's plan limits how many schedules it can have. When that limit is reached, `PUT` returns `402`.
* On the free plan, a schedule expires after at most 3 months. A later or omitted `expires_at` is set to that limit.
* Materialized view refreshes are listed, but you change them with the [Materialized Views API](https://docs.dune.com/api-reference/materialized-views/overview.md).

## Cron Expressions

Schedules use 5-part cron expressions in UTC. Only these forms are supported:

| Expression | Runs |
| - | - |
| `*/15 * * * *`, `*/20 * * * *`, `*/30 * * * *` | Every 15, 20, or 30 minutes |
| `0 * * * *` | Every hour |
| `0 */N * * *`, with N one of 2, 3, 4, 6, 8, 12 | Every N hours |
| `M H * * *` | Every day at H:M |
| `M H * * D` | Every week on day D (0 is Sunday) at H:M |

M is `0` or `30`, and H is `0` to `23`. Other expressions return `400`.

> [card] [List Schedules](https://docs.dune.com/api-reference/schedules/endpoint/list.md)
>
> List the query, dashboard, and materialized view schedules you can see.

> [card] [Set Query Schedule](https://docs.dune.com/api-reference/schedules/endpoint/set-query.md)
>
> Run a saved query on a schedule, or change its schedule.

> [card] [Delete Query Schedule](https://docs.dune.com/api-reference/schedules/endpoint/delete-query.md)
>
> Stop running a saved query on a schedule.

> [card] [Set Dashboard Schedule](https://docs.dune.com/api-reference/schedules/endpoint/set-dashboard.md)
>
> Refresh a dashboard on a schedule, or change its schedule.

> [card] [Delete Dashboard Schedule](https://docs.dune.com/api-reference/schedules/endpoint/delete-dashboard.md)
>
> Stop refreshing a dashboard on a schedule.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.