Skip to main content

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.

  1. 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 a 400.
  2. 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).
  3. The row is inserted, then its first next_run_at is 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.

Schedule frequency, the stored value, and the minimum plan it needs
FrequencyStored valueMinimum planNotes
HourlyhourlyElite SupporterFires at the top of every hour, so the preferred hour has no effect. The heaviest option, reserved for the top tier.
Every 6 hours6hourlyPro SupporterFour runs a day, anchored to your preferred hour plus the interval.
DailydailyAny plan that can scheduleOnce a day at your preferred hour.
WeeklyweeklyAny plan that can scheduleOnce a week on your preferred day and hour. This is the fallback for a missing or unrecognised frequency.
MonthlymonthlyAny plan that can scheduleOnce 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.

Default number of schedules each plan may keep active
PlanSchedules
Free3
Core Supporter5
Pro Supporter10
Elite Supporterunlimited

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 /schedules directly, 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.

GET
/schedules

List 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

JSON
{
  "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
    }
  ]
}
Rows come back as stored under a schedules key: snake_case columns, times in UTC, next_run_at as an ISO-8601 instant.
You see your own schedules and any on a team you are a member of. There is no way to see another user's personal schedules.

Error Responses

401
No session cookie
POST
/schedules

Create 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

JSON
{
  "url": "https://example.com",
  "frequency": "daily",
  "preferredHourUtc": 9,
  "preferredDayOfWeek": 1,
  "preferredDayOfMonth": 1
}

Response
200 OK

JSON
{
  "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
}
frequency accepts hourly | 6hourly | daily | weekly | monthly. Anything else, or a missing value, falls back to weekly.
hourly needs the Elite Supporter plan and 6hourly needs Pro Supporter or above. daily, weekly, and monthly carry no extra frequency gate, but every schedule counts against your per-plan schedule limit.
preferredHourUtc is a UTC hour (0-23). The web UI holds your local time and converts to UTC once at submit. Omitted or out of range, it clamps to the current UTC hour; the day fields clamp the same way.
preferredDayOfWeek (0-6, Sunday=0) is read only for weekly; preferredDayOfMonth (1-28) only for monthly. Day of month is capped at 28 so every month has that day.
The URL must parse, stay under MAX_URL_LENGTH, and pass the same SSRF safe-target check every scan route uses: a public HTTP(S) host, never localhost, a private or link-local range, or a cloud-metadata address.
Creating a schedule sends the Scheduled Scans notification email if you have it enabled.

Error Responses

400
URL missing, unparseable, too long, SSRF-blocked, over your plan's schedule limit, or a frequency your plan does not unlock
401
No session cookie
403
Scheduled scans are disabled on this deployment (FEATURE_SCHEDULED_SCANS is off)
PATCH
/schedules

Pause, 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

JSON
{
  "id": 42,
  "active": false
}

Response
200 OK

JSON
{
  "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
}
Send { id, active: false } to pause and { id, active: true } to resume. A paused schedule is skipped by the worker until you resume it.
teamId assigns or clears the team a schedule is shared with; pass null to unshare. Only the schedule's owner may change the team, and the target must be a team you can assign to.
active can be toggled by the owner or by a team co-member whose role grants scan management; reassigning teamId is owner-only.
At least one of active or teamId must be present, or you get a 400.

Error Responses

400
Nothing to update, bad types, or a teamId you cannot assign
401
No session cookie
403
You can read this schedule but are not allowed to change it
404
Schedule not found, or not visible to you (anti-enumeration)
DELETE
/schedules

Delete 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

JSON
{
  "id": 42
}

Response
200 OK

JSON
{
  "success": true
}
The owner, or a team co-member with scan-management access, can delete.
A stranger's id returns { success: true } without deleting, the same anti-enumeration behaviour as the rest of the per-resource routes.
Deleting a schedule sends the Scheduled Scans notification email if you have it enabled.

Error Responses

401
No session cookie
403
You can read this schedule but are not allowed to delete it

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_at has passed.
  • Claims safely: rows are claimed with FOR UPDATE SKIP LOCKED and their next_run_at is 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_at is stamped and the real next_run_at is 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.
Scheduled Scans for Recurring Website Audits | VulnRadar