Schedules
A watchlist runs on a cadence (every 15 minutes, start to start) or on a cron schedule in your time zone (08:00 New York time on weekdays). How each works, and what happens around them.
Embed
<a href="https://scrapelyserp.com/docs/schedules"><img src="https://scrapelyserp.com/docs/_api/public/orgs/affc5b0f-d3c2-423a-8143-9d10db5736ae/spaces/981e6275-da3f-446c-82de-889f59c83b6f/pages/24f48b19-2427-4df4-b46f-30b5769369b8/social-card.svg?v=3e7ae33eec8b" alt="Schedules" width="600" height="315"></a>A watchlist runs on a cadence (every 15 minutes, start to start) or on a cron schedule in your time zone (08:00 New York time on weekdays). How each works, and what happens around them.
Cadence or cron
Cadence ( | Cron ( | |
|---|---|---|
Runs | At a fixed interval, start to start | At wall-clock times in a time zone |
Example |
|
|
Range | From 5 minutes to 7 days | At most every 5 minutes |
Best for | Monitoring: "never more than 15 minutes stale" | Business hours, reports, a quiet night, "after the 6am price update" |
After a manual run | The next run is one cadence after it | The wall-clock times stay; a time less than 5 minutes after the manual run is skipped |
Send exactly one of them. Sending both, or a timezone with every, is a 400.
Cron expressions
Standard five-field cron, read in the list's timezone (an IANA name such as Europe/London; default UTC):
Field | Values | Also |
|---|---|---|
minute | 0–59 | Lists |
hour | 0–23 | |
day of month | 1–31 | When both day fields are restricted, a day matches either (the classic cron rule) |
month | 1–12 or | |
day of week | 0–7 or | 0 and 7 are Sunday; |
Expression | Runs |
|---|---|
| Every 30 minutes, on the hour and half hour |
| At 08:00 on weekdays |
| Every hour of the working day |
| At 06:15 on the 1st of every month |
| The usual shorthands (midnight, Sunday, the 1st, 1 January) |
Daylight saving time
A time that does not exist on the day the clocks go forward (02:30 in New York) runs once, shifted forward by the gap (03:30), so a daily schedule never silently skips a day. A time that happens twice when the clocks go back runs once, at its first occurrence.
In practice
A list reports its schedule as
schedule:{ "type": "every", "every": "15m", "every_seconds": 900 }or{ "type": "cron", "cron": "0 8 * * 1-5", "timezone": "America/New_York" }, withnext_run_at. On a cron listeveryisnull.Runs of one list never overlap: a scheduled time that comes while the previous run is still going is skipped, and the list carries on at the next one.
A paused list keeps its schedule but does not run (
next_run_atisnull). On resume, an overdue cadence list runs at once; a cron list waits for its next time.PATCHwitheveryorcronswitches between the two;timezonealone re-zones a cron list. A new cadence counts from the last run.
- cURL
- Python
- Node.js
curl -X PATCH "https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61" \
-H "Authorization: Bearer $SCRAPELY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cron":"0 8 * * 1-5","timezone":"America/New_York"}'import os
import requests
HEADERS = {"Authorization": f"Bearer {os.environ['SCRAPELY_API_KEY']}"}
r = requests.patch(
"https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61",
headers=HEADERS,
json={"cron": "0 8 * * 1-5", "timezone": "America/New_York"},
timeout=30,
)
r.raise_for_status()
data = r.json()const res = await fetch('https://api.scrapelyserp.com/v1/watchlists/wl_3f1c2a9e8d4b4c61', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.SCRAPELY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ cron: '0 8 * * 1-5', timezone: 'America/New_York' }),
signal: AbortSignal.timeout(30_000),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const data = await res.json();Full reference → PATCH /v1/watchlists/{id}, POST /v1/watchlists/{id}/run