> Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

---
title: Schedules
"og:image": "https://libretto.sh/docs/og/libretto-cloud-api/schedules.png"
---

> Use the schedules API to run a deployed workflow on a recurring cron-based interval.

All routes on this page require `x-api-key`.

### Callback behavior

Schedules create jobs in the future. Each schedule can carry its own `callback_url` and `callback_secret`.

If a scheduled job has a callback configured, that per-job callback takes precedence over stored tenant webhook endpoints. Use schedule-level callbacks when you want recurring jobs to report to a specific endpoint.

### POST `/v1/schedules/create`

Create a recurring schedule for a deployed workflow.

Request fields:

* `workflow`
* `params`
* `cron_expr`
* `timezone`: optional, default `UTC`
* `timeout_seconds`: optional, default `900`
* `start_url`: optional start URL override for browser launch
* `gpu`: optional boolean GPU override
* `viewport`: optional `{ width, height }` viewport override
* `callback_url`: optional
* `callback_secret`: optional
* `skip_callbacks`: optional, default `false`
* `residential_proxy`: optional residential proxy location object
* `enabled`: optional, default `true`

If you set `callback_url`, you must also set `callback_secret`.

Prefer declaring `startUrl`, `gpu`, and `viewport` on the workflow definition so they travel with the deploy artifact. Use the schedule-level fields when you need a one-off override, or until the hosted executor applies workflow launch metadata automatically.

Use `residential_proxy` for recurring workflows that need traffic to originate from a specific residential proxy country, US state, city, ZIP code, or ASN. See [Residential proxy locations](/libretto-cloud-hosting/stealth#residential-proxy-locations) for the supported fields and combination rules.

Response fields:

* `success`
* `schedule`

### POST `/v1/schedules/list`

List schedules for the current tenant.

Request fields:

* `enabled`: optional boolean filter
* `workflow`: optional workflow-name filter
* `limit`: optional page size, default `50`, max `200`

Response fields:

* `schedules`

### POST `/v1/schedules/get`

Fetch one schedule.

Request fields:

* `id`

Response fields:

* `schedule`

### POST `/v1/schedules/update`

Update a schedule.

Request fields:

* `id`
* `params`: optional
* `cron_expr`: optional
* `timezone`: optional
* `timeout_seconds`: optional
* `callback_url`: optional string or `null`
* `callback_secret`: optional string or `null`
* `skip_callbacks`: optional
* `residential_proxy`: optional object or `null`
* `enabled`: optional

To clear the callback, set both `callback_url` and `callback_secret` to `null`.
To clear the configured residential proxy location, set `residential_proxy` to `null`.

Response fields:

* `schedule`

### POST `/v1/schedules/delete`

Delete a schedule.

Request fields:

* `id`

Response fields:

* `success`
* `id`

### Shared schedule response shape

The `schedule` object returned by the schedules endpoints includes:

* `id`
* `workflow`
* `params`
* `cron_expr`
* `timezone`
* `timeout_seconds`
* `residential_proxy`
* `callback_url`
* `skip_callbacks`
* `enabled`
* `next_fire_at`
* `last_fire_at`
* `last_job_id`
* `last_error`
* `consecutive_failures`
* `created_at`
* `updated_at`

<CardGroup cols={3}>
  <Card title="Webhooks" icon="lucide:webhook" href="/libretto-cloud-api/webhooks">
    Compare stored tenant webhooks with schedule-level callbacks.
  </Card>

  <Card title="Deployments and Workflows" icon="rocket" href="/libretto-cloud-api/deployments-and-workflows">
    Manage the workflows that schedules invoke.
  </Card>

  <Card title="Libretto Cloud API overview" icon="book-open" href="/libretto-cloud-api/overview">
    See the shared request format.
  </Card>
</CardGroup>