A passing test suite only helps if it keeps passing. Your checkout flow works today, but a dependency ships a breaking change at 2 a.m., a certificate expires over the weekend, or a config drift takes down the payments endpoint on a Sunday. You find out from an angry customer instead of a test run. The fix is boring and reliable: run your API tests on a schedule, without a human clicking a button, and get told the moment something breaks.
Apidog has a built-in Scheduled Tasks feature for exactly this. You point it at test scenarios you already built, set a cadence, pick a machine to run on, and wire up alerts. This guide walks through all of it honestly, including where the current limits are. If you are new to running unattended checks against live endpoints, our primer on API monitoring sets the wider context, and the Apidog Scheduled Tasks documentation is the source of record for the UI.
One quick note before you start. The Scheduled Tasks feature is labeled in Beta right now, and the exact number of scheduled runs your account gets depends on your plan. Keep both in mind as you read.
What scheduled tasks do (and how they differ from scheduled scrapers)
A scheduled task in Apidog runs one or more saved Test Scenarios on a recurring cycle. Think nightly regression across your core API, a smoke check every few hours against staging, or a weekend health sweep. The task remembers which scenarios to run, which environment to hit, how often to fire, which machine executes the work, and who to notify when it fails.
If you have seen the phrase “scheduled tasks” attached to web scraping or data collection, that is a different thing. This feature is not about crawling pages on a timer. It lives inside the Tests module and drives your API test scenarios: assertions, chained requests, extracted variables, the works. The output is a pass or fail report on your API contract, not a scraped dataset.
That distinction matters because it changes what you configure. You are not writing selectors or crawl rules. You are choosing existing test scenarios and telling Apidog when and where to run them.
Before you start: configure a self-hosted Runner
Here is the prerequisite that trips people up. To run scheduled tasks, you first need to configure a self-hosted Runner. The docs are explicit about this.
A Runner is a machine that executes the test suite. When a scheduled task fires, Apidog does not run the requests in your desktop client; it hands the job to the Runner you selected, and every request in the suite is sent from that machine. A CI box, a small always-on server, or a dedicated VM all work well. Whatever you pick stays awake and reachable on the schedule you want.
The runner target field offers two choices: Apidog Cloud, marked “coming soon,” or a self-hosted Runner. Since Apidog Cloud is not available yet, a self-hosted Runner is the only working option today. Do not plan around cloud execution until it ships.
Because requests originate from the Runner’s machine, its network environment shapes your results. A Runner behind a corporate VPN, a different region, or a firewalled subnet may see different responses than your laptop does. That is usually what you want for realistic monitoring, but it is worth knowing when a scheduled run disagrees with a local one.
Step by step: create a scheduled task
With a Runner registered, the rest happens in the client. The running example below is a nightly regression suite for an e-commerce API that covers user signup, product listing, cart, and a checkout backed by Stripe.
1. Open Scheduled Tasks in the Tests module
Open the Tests module in the Apidog client. In the Tests folder tree, click Scheduled Tasks to view and manage every scheduled task in the project. All tasks across the project show up here under the Scheduled Tasks section, so this is your one place to see what is running and when.
2. Create the task
Click + New to create a new scheduled task. You can also create a folder here to group related tasks, which is handy once you have separate suites for staging and production or for different services.
Give the task a clear Task Name and Description. These exist to distinguish tasks and explain their purpose, so future-you knows what “Nightly regression, prod” actually covers without opening it. Each task also has an enable/disable toggle, and tasks in the tree can be enabled or disabled at any time.
3. Select the test scenarios to run
Under Test Scenario, pick one or more scenarios to include. For the e-commerce example you might select “Signup and login,” “Browse and add to cart,” and “Checkout with Stripe test card” so a single task covers the whole critical path.
Each scenario can carry its own execution settings: Environment, test data, iterations, delay, and whether to save requests and responses. If you would rather not tune each one, turn on Use same execution config to apply a single runtime configuration to every selected scenario at once. That keeps a large suite consistent and quick to set up.
Environment selection is the setting people care about most. Point a nightly production monitor at your prod environment, and point a pre-release smoke test at staging. Because each scenario can specify its own environment, one task can even mix targets if you need it to, though keeping a task to a single environment is cleaner to reason about.
4. Set the run cycle
Set the run-schedule field to the cadence you want. Depending on which screen you are on, this field reads Run Cycle or Run Mode; it is the same setting, and the label wording varies across the UI. The docs give concrete examples you can mirror: every Sunday at 11 PM, every 6 hours, or every 8 hours.
For nightly regression, a daily late-night run keeps noise low and catches problems before the workday. For a staging smoke test, every 6 hours gives you faster feedback without hammering the environment.
5. Choose where it runs
Set the runner field to your self-hosted Runner. Like the schedule field, this one is labeled inconsistently across screens as Runs on, Run On, or Runs On; they all mean the same thing, the machine that executes the suite. Apidog Cloud appears here too but is coming soon, so choose your self-hosted Runner. If you have registered several general-purpose Runners, pick the specific one you want, for example a Runner that sits inside the same VPC as your API.
Remember that all requests initiated in the test suite are sent from the machine specified here, so choose a Runner whose network sees your API the way real traffic does.
6. Turn on notifications
Enable Notification so the task tells you when something breaks. The docs recommend this for scheduled tasks, and it is the whole point of unattended runs: silence should mean success, and a failure should reach you fast.
Apidog supports these channels by name: Slack, Teams, Webhook, Jenkins, and Email. For Email, addresses of project members auto-complete, and you can type in non-member addresses manually for an on-call rotation or a shared inbox. Slack drops failures straight into your team channel; the Webhook option lets you fan out to anything else you run, from PagerDuty to a custom endpoint.
You also choose when alerts fire: after every run, or on failures only. For a healthy nightly suite, failures-only keeps the channel quiet until it matters. During a shaky rollout, every-run gives you a heartbeat that confirms the job is even executing.
7. Save and enable
Flip the task’s toggle to enable it, and it starts running on the cadence you set. You can disable it later without deleting it, which is useful during a planned outage or a noisy migration window.
8. Read the run history
After each run, results upload automatically from the Runner back to the server. Open the Scheduled Tasks - Run History section in the client to see them. This is your audit trail: which run passed, which failed, which assertion broke, and when. When an alert lands in Slack, Run History is where you go to see the detail behind it.
Advanced settings and variations
Once the basic task runs, a few options make it sturdier.
Variable scope. When your scenarios pass data between runs, Apidog gives you three sharing levels, smallest to largest: Share only in the current test scenario, which keeps a variable in a dedicated file for that one scenario; Share across all test scenarios in the current scheduled task, which lets scenarios in the same task read each other’s values; and Share across all scheduled tasks in the current scheduled task folder, the widest scope. Pick the smallest scope that still lets your data flow, so an auth token from one scenario does not leak into an unrelated one.
Variable persistence. Values only carry from one run to the next if the Keep variable values option is enabled on the test scenario design page. If your nightly run needs yesterday’s captured order ID or a refreshed token, turn this on. Without it, each run starts clean and any cross-run assumption breaks quietly.
Grouping with folders. As your suite grows, create folders under Scheduled Tasks to separate, say, production monitors from pre-release checks. Folder-level variable scope then lets a group of related tasks share setup cleanly.
Plan limits. The number of scheduled runs you get depends on your subscription. The docs point to the Apidog pricing page for the exact figures, so check your plan before you set an aggressive every-hour cadence. If you need deeper coverage of grouping and heavier scheduling patterns, our walkthrough of advanced scheduled tasks goes further, and the sibling guide on conditional logic in API test scenarios helps you build scenarios worth scheduling in the first place. For teams standing up their first unattended checks, the nightly API test runs in CI piece pairs well with this one.
Automate the workflow with the Apidog CLI
The Scheduled Tasks UI is one path. The Apidog CLI is the third, and it is a real one: you run a saved scenario headlessly, then let cron or your CI provider handle the cadence. To be clear, the CLI has no native schedule command; the scheduling lives outside Apidog in the tool you already trust for cron.
Install and authenticate, then run a scenario by id against a chosen environment. The Apidog CLI installation guide covers token setup in full:
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli,junit
Here -t is the test scenario id, -e is the environment id, and -r is the reporter (cli, html, or junit, comma-separated for several). To run it nightly with cron, add one line:
0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1
Or trigger it from a scheduled GitHub Actions job. Either way the JUnit report drops into your existing pipeline dashboards. See Apidog CLI in your CI/CD pipeline for the full setup, including cron and GitHub Actions schedule triggers.
FAQ
Can I run scheduled tests on Apidog Cloud today? Not yet. The runner target lists Apidog Cloud as “coming soon,” so a self-hosted Runner is the only working execution machine for now. Register a Runner first, then select it in the task.
How often can scheduled tasks run? As often as your plan allows. Cadence itself is flexible, with documented examples like every 6 hours or every Sunday at 11 PM, but the count of scheduled runs is gated by your subscription. Check the Apidog pricing page for your tier’s exact limit rather than assuming a number.
How do I get notified only when a test fails? In the task’s Notification settings, choose the failures-only option instead of every run, then add a channel: Slack, Teams, Webhook, Jenkins, or Email. This keeps your channel quiet on green nights and loud when something breaks. Pair it with a lightweight API health check for a fast liveness signal alongside the deeper regression suite.
Why do my scheduled results differ from my local test runs? Because the requests come from the Runner’s machine, not your laptop. Its network, region, and any VPN or firewall shape the responses. That is expected, and it is often the more realistic view of what your users hit.
My variables reset every run. What did I miss? The Keep variable values option on the test scenario design page. Enable it so captured values persist from one run to the next. Without it, each scheduled run starts fresh and any cross-run dependency fails.
Wrapping up
Scheduled tests turn “we think the API works” into “we know, and we would have heard by now if it did not.” Build your scenarios once, register a self-hosted Runner, set a Run Cycle, wire up Slack or email on failure, and let it run while you sleep. When you want the same checks inside a pipeline, the CLI plus cron gives you the third path with zero extra tooling. Download Apidog to set up your first scheduled regression suite. It is free to start, no credit card required.
