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:
workflowparamscron_exprtimezone: optional, defaultUTCtimeout_seconds: optional, default900start_url: optional start URL override for browser launchgpu: optional boolean GPU overrideviewport: optional{ width, height }viewport overridecallback_url: optionalcallback_secret: optionalskip_callbacks: optional, defaultfalseresidential_proxy: optional residential proxy location objectenabled: optional, defaulttrue
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.Response fields:
successschedule
POST /v1/schedules/list
List schedules for the current tenant.
Request fields:
enabled: optional boolean filterworkflow: optional workflow-name filterlimit: optional page size, default50, max200
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:
idparams: optionalcron_expr: optionaltimezone: optionaltimeout_seconds: optionalcallback_url: optional string ornullcallback_secret: optional string ornullskip_callbacks: optionalresidential_proxy: optional object ornullenabled: 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:
successid
Shared schedule response shape
The
schedule object returned by the schedules endpoints includes:idworkflowparamscron_exprtimezonetimeout_secondsresidential_proxycallback_urlskip_callbacksenablednext_fire_atlast_fire_atlast_job_idlast_errorconsecutive_failurescreated_atupdated_at