Automation
Scheduled Scans
Point a URL at a schedule and VulnRadar re-scans it on its own: hourly, every 6 hours, daily, weekly, or monthly. Each run goes through the same engine a manual scan uses, lands in your history, and fires your webhooks and alerts, so a regression shows up without anyone remembering to check.
- Frequencies
- 5
- Schedules by plan
- 3-∞
- Auth required
- session
Overview
A scheduled scan is a stored URL plus a cadence. A background worker wakes up on a short interval, finds the schedules that are due, and runs each one through the exact same scan path a manual scan takes. The result is a normal entry in your scan history, tagged with a scheduled source, so everything that reads a scan (the history view, reports, the diff against the previous run) works on it unchanged.
The point is regression detection you do not have to remember. Set a production URL to re-scan daily and you get told when a new critical or high finding appears, when a header you fixed comes back, or when the target starts failing safety checks, all without opening the app. Manage schedules in the app under /profile in the Developer tab, or over the https://vulnradar.dev/api/v3/schedules endpoints below.
Creating a schedule
In the app, open /profile, go to the Developer tab, and pick Scheduled Scans. Paste a URL, choose a frequency, and set the time of day (and day of week or month, when the frequency needs one). The pickers are in your local time; the browser converts them to UTC once before sending.
- The URL is checked before anything is stored: it has to parse, stay under the deployment's
MAX_URL_LENGTH, and clear the same SSRF safe-target check a live scan uses. A private, loopback, link-local, or cloud-metadata target is rejected with a400. - Your plan is checked twice over: the schedule has to fit under your per-plan count limit, and the frequency has to be one your plan unlocks (see the next section).
- The row is inserted, then its first
next_run_atis computed from your frequency and time-of-day preferences and written back. From then on the worker owns that column.
Prefer the API? The same create call is one POST, documented under The schedules API below. It is session-authenticated, so it runs with your logged-in session cookie, not a Bearer key.
Frequencies and plan limits
Five cadences. The two sub-daily ones are gated by plan tier, because an hourly schedule is up to 24 times the scan volume of a daily one. The other three carry no extra frequency gate beyond being able to schedule at all.
| Frequency | Stored value | Minimum plan | Notes |
|---|---|---|---|
| Hourly | hourly | Elite Supporter | Fires at the top of every hour, so the preferred hour has no effect. The heaviest option, reserved for the top tier. |
| Every 6 hours | 6hourly | Pro Supporter | Four runs a day, anchored to your preferred hour plus the interval. |
| Daily | daily | Any plan that can schedule | Once a day at your preferred hour. |
| Weekly | weekly | Any plan that can schedule | Once a week on your preferred day and hour. This is the fallback for a missing or unrecognised frequency. |
| Monthly | monthly | Any plan that can schedule | Once a month on your preferred day (1-28) and hour. |
How many you can keep
Separate from the frequency gate, each plan caps how many schedules you can have at once. The count is enforced on create against the schedules you personally own. These are the shipped defaults; an admin can retune them live, where -1 means unlimited and 0 disables scheduling on that plan.
| Plan | Schedules |
|---|---|
| Free | 3 |
| Core Supporter | 5 |
| Pro Supporter | 10 |
| Elite Supporter | unlimited |
A downgrade does not break an existing schedule
The frequency gate is re-checked at run time, not just at creation. If your plan drops below what a sub-daily schedule needs, the worker defers that run and reschedules it at its normal cadence instead of deleting or disabling it. Re-upgrade and the next occurrence simply runs again.
Time of day and timezones
Schedules are stored entirely in UTC. The row carries a preferred_hour_utc (0-23), a preferred_day_of_week (0-6, Sunday is 0, used only for weekly), and a preferred_day_of_month (1-28, used only for monthly). The app never asks you to think in UTC: the time-of-day pickers hold your local selection and the browser converts to UTC exactly once, at submit.
- The hour and day are converted together, not separately, so a late-night local time that lands on a different UTC day picks the right day rather than silently sliding by one.
- Day of month is capped at 28. Every month has a 28th, so a monthly schedule never has to guess what to do in February.
- Calling
POST /schedulesdirectly, you send the UTC values yourself. Omit one, or send an out-of-range number, and it clamps to the current moment (the current UTC hour, weekday, or day of month).
Where results go
A scheduled run is a normal scan. It writes a scan_history row, so it shows up in your history, in reports, and in the diff against the previous scan of that URL. It has no per-run privacy toggle, so its public-or-private visibility follows your account's default scan-privacy setting, the same fallback a manual scan uses when its request omits the flag.
- Scheduled Scans Completed email: after each completed run, if you have that notification toggle on. It is its own preference, distinct from the routine scan-complete email.
- No scan-complete spam: the ordinary "scan complete" email that a manual scan sends is suppressed for scheduled runs, so an hourly schedule does not flood your inbox.
- New critical or high alert: you are still emailed when a run turns up a genuinely new critical or high finding compared to the previous scan of that URL. A finding that was already there on the last run does not re-alert, so a persistent issue on an hourly schedule does not notify every hour.
- Webhooks: every active webhook fires on a completed scheduled run, both your own and any assigned to the schedule's team. The payload is identical to a manual scan's; see the webhooks reference.
Pausing, teams, and auto-disable
Pause and resume
Every schedule has an active flag. Pause one from the row's pause button in the app, or with PATCH /schedules sending { id, active: false }. A paused schedule is skipped by the worker until you resume it; nothing else about it changes, and flipping it back on is one call.
Auto-disable on an unsafe target
The worker re-runs the SSRF safe-target check before every scan, not just at creation. If a target that was public when you created the schedule later resolves to a private or blocked address (DNS rebinding, an infra change), the worker sets the schedule to active = false and emails you why. That is deliberate: unlike a transient network blip, this condition describes the target itself and will not clear on its own. Point the URL back at a public host and re-enable it with PATCH.
Sharing with a team
A schedule can be assigned to a team so a co-member can manage it and the team's webhooks fire for its runs. Assign or clear the team with the teamId field on PATCH (pass null to unshare). Only the owner can change the team, but pausing and resuming is open to any team member whose role grants scan management. GET /schedules returns your own schedules plus every schedule on a team you belong to. Each row on the Scheduled Scans page carries the same picker, so you do not have to send the PATCH yourself.
The schedules API
Four methods on one path, all under https://vulnradar.dev/api/v3. Every one is session-authenticated: a logged-in session cookie, not a Bearer API key. Request bodies use camelCase (preferredHourUtc); the rows you get back use the stored snake_case column names.
/schedulesList your schedules
Returns every schedule you own plus any schedule assigned to a team you belong to, newest first. Session-authenticated only: this route reads the logged-in user from the session cookie and does not accept a Bearer API key.
Response 200 OK
{
"schedules": [
{
"id": 42,
"url": "https://example.com",
"frequency": "daily",
"active": true,
"last_run_at": null,
"next_run_at": "2026-08-25T09:07:00.000Z",
"created_at": "2026-08-24T14:20:00.000Z",
"team_id": null,
"preferred_hour_utc": 9,
"preferred_day_of_week": 1,
"preferred_day_of_month": 1
}
]
}Error Responses
/schedulesCreate a schedule
Registers a recurring scan and returns the created row with a 201. The URL is validated the same way a live scan target is; the frequency and time-of-day preferences are stored in UTC and used to compute the first next_run_at.
Request Body
{
"url": "https://example.com",
"frequency": "daily",
"preferredHourUtc": 9,
"preferredDayOfWeek": 1,
"preferredDayOfMonth": 1
}Response 200 OK
{
"id": 42,
"url": "https://example.com",
"frequency": "daily",
"active": true,
"last_run_at": null,
"next_run_at": "2026-08-25T09:07:00.000Z",
"created_at": "2026-08-24T14:20:00.000Z",
"team_id": null,
"preferred_hour_utc": 9,
"preferred_day_of_week": 1,
"preferred_day_of_month": 1
}Error Responses
/schedulesPause, resume, or reassign a schedule
Toggle a schedule on or off, and/or move it to a different team. Send only what you want to change; the returned row reflects the update.
Request Body
{
"id": 42,
"active": false
}Response 200 OK
{
"id": 42,
"url": "https://example.com",
"frequency": "daily",
"active": false,
"last_run_at": null,
"next_run_at": "2026-08-25T09:07:00.000Z",
"created_at": "2026-08-24T14:20:00.000Z",
"team_id": null,
"preferred_hour_utc": 9,
"preferred_day_of_week": 1,
"preferred_day_of_month": 1
}Error Responses
/schedulesDelete a schedule
Permanently removes a schedule. Deleting one you cannot see returns success without touching anything, so the endpoint never confirms an id belongs to someone else.
Request Body
{
"id": 42
}Response 200 OK
{
"success": true
}Error Responses
How runs are triggered
Nothing in the create call runs a scan. A background worker does, on a poll, and it is built to stay safe under a backlog or a crash rather than to fire on the exact second.
- Polls every 2 minutes (the default), in-process, in a long-lived deployment only. Each tick claims the due, active rows whose
next_run_athas passed. - Claims safely: rows are claimed with
FOR UPDATE SKIP LOCKEDand theirnext_run_atis immediately pushed about 15 minutes forward as a soft lock. Two workers, or two overlapping ticks, never double-run the same schedule, and a crash mid-batch self-heals once that buffer expires. - Bounded concurrency: claimed schedules run a handful at a time (5 by default), not all at once. A large backlog runs a bit late, in order, instead of launching hundreds of simultaneous scans.
- Isolated failures: one schedule's scan throwing never stops the batch. It is logged, rescheduled, and the rest of the tick continues.
- After a run,
last_run_atis stamped and the realnext_run_atis recomputed from the same shared timing logic the create call used, so the two can never drift apart.
Bulk scanning
A schedule repeats one URL over time. A bulk scan is the other axis: many URLs, once. Paste a list into the scan form, or POST /api/v3/scan/bulk with an array. Either way you get a scan id per URL back immediately and the batch drains in the background, so you can close the tab and read the results from your history later.
How many URLs
The cap per batch is a plan limit, listed alongside the others on the Plans and Billing page. Going over it is refused outright rather than silently truncated, so you always know which URLs were accepted. How often you may submit a batch is capped separately, per account, on the Rate Limits page.
What happens to each URL
- Every URL is validated and checked against the blocklist before it is charged a scan, so an unscannable URL in the middle of your list costs you nothing and does not stop the rest of the batch.
- Each accepted URL gets its own scan row and its own entry in the response, marked either queued with an id or refused with a reason. Read the response rather than assuming the whole list went through.
- URLs run one at a time, deliberately: this runs as a single process with no job queue, so a batch of 100 must not become 100 simultaneous scans.
- Each URL runs the same engine, the same watchdog and the same progress reporting as a single scan, and lands in your history the same way. There is no second, weaker bulk scanner.
- The whole batch has its own wall-clock budget. If it runs out, URLs that never started are closed as failed rather than left sitting as pending forever.