Schedules

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
disable_default_proxy: optional boolean; Kernel only. Disables Kernel's default residential stealth proxy so traffic uses direct egress. Mutually exclusive with residential_proxy.
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 for the supported fields and combination rules.

Use disable_default_proxy when the default managed proxy cannot reach the target (for example ERR_TUNNEL_CONNECTION_FAILED). It cannot be combined with residential_proxy.

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
disable_default_proxy: optional boolean; Kernel only. Mutually exclusive with a non-null residential_proxy.
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. To clear direct-egress mode and restore the default proxy, set disable_default_proxy to false.

Response fields: