API Testing: Schedules
Overview
Use this page to create and manage cron schedules for API flows. A schedule is a saved trigger that runs a specific API flow automatically at defined times, using a cron expression, instead of you starting that flow by hand. It turns a recurring validation or monitoring check into an unattended process that runs on its own cadence.
A schedule targets a flow that must already exist and have at least one committed revision on API Testing: Flows; a Draft flow accepts a schedule but the schedule only fires once you commit a revision, and an Archived flow's schedules never fire. Optional overrides point a schedule at a different environment or auth profile from API Testing: Environments and API Testing: Auth Profiles, and alert profiles from Alerting: Profiles notify you of the outcome. Every fire, scheduled or manual, is recorded on API Testing: Run History.
This page lists every schedule with its flow, cron pattern, timezone, enabled state, and next and last run outcome. From here you add, edit, enable or disable, run immediately, and delete schedules.
Key concepts
- schedule - A saved trigger that runs a specific API flow automatically on a cron cadence, instead of you starting that flow by hand each time. (related: API Testing: Flows)
- cron expression - A 5-field pattern (minute hour day month weekday) that defines exactly when a schedule fires, for example 0 7 * * 1-5 for 7:00 AM every weekday.
- environment override - An environment chosen for a schedule that replaces the flow's own default environment for just that schedule's runs. (related: API Testing: Environments)
- auth profile override - An auth profile chosen for a schedule that replaces the flow's own default auth profile for just that schedule's runs. (related: API Testing: Auth Profiles)
- alert profile (Testing scope) - A notification rule, scoped to Testing alerts, that you attach to a schedule so you're notified about its run outcomes. (related: Alerting: Profiles)
When to use it
- To automate a recurring smoke or regression check on an API flow without manually starting a run.
- When a flow needs to fire on a specific cadence and in a specific timezone, such as business hours in one region.
- To attach alert profiles so you're notified automatically when a scheduled run fails.
- To pause a flow's automated runs temporarily without deleting the schedule.
- To investigate why a scheduled run didn't fire on time or failed, using the Last Run status.
- To fire a schedule immediately, outside its cron cadence, for an ad hoc check.
Before you begin
- An API flow exists with at least one committed revision, created on API Testing: Flows; a Draft flow can be scheduled but won't fire until committed.
- The target flow's status is Active, not Archived; an Archived flow's schedules never fire.
- If you plan to use Environment override, the target environment exists on API Testing: Environments.
- If you plan to use Auth profile override, the target auth profile exists on API Testing: Auth Profiles.
- If you want run-outcome notifications, the relevant Testing-scope alert profile exists on Alerting: Profiles.
- Your role holds the grant to create and edit schedules; otherwise Add Schedule is hidden and the row icons appear disabled with an explanatory tooltip.
Common workflows
Automate a recurring flow run
Persona: Load-test operator
- On the Schedules page, select Add Schedule.
- Expect: The schedule dialog opens with empty Name, Flow, and Cron expression fields.
- Enter a descriptive Name, choose the Flow to run, and enter a Cron expression or select a cron preset.
- Expect: The fields accept your entries, or Name is required. / Cron expression is required. appears in red if either is left blank.
- Optionally set Timezone, Environment override, Auth profile override, Debug mode, Alert profiles, and retry settings, then select Save.
- Expect: The dialog closes and the new schedule appears as a row in the table with Enabled set to On and a Next Run timestamp calculated from the cron expression.
Verify: The new row shows the Name, Flow, Cron, and Timezone you entered and a future Next Run timestamp. If the target flow is still a Draft, the row still lists a Next Run, but the flow must be committed on API Testing: Flows before that run actually fires.
Pause and resume a schedule without deleting it
Persona: Admin
- Locate the schedule in the table and select its Enabled toggle.
- Expect: The toggle switches from On to Off and the schedule stops appearing in the cron's fire queue.
- Select the same toggle again when you want automated runs to resume.
- Expect: Enabled switches back to On and Next Run shows the following scheduled time.
Verify: The Enabled column reads Off while the schedule is paused, and On with a populated Next Run once you resume it.
Investigate and recover from a failed scheduled run
Persona: Load-test operator
- Check the Last Run column for a row showing a red Failed badge.
- Expect: You see the timestamp of the failed fire beneath the schedule's other details.
- Select Run now on that row to re-trigger the flow immediately.
- Expect: The flow starts a new run outside the cron cadence, or the dialog reports a refusal reason, for example an invalid environment or auth override, or the flow not being Active.
- If the run is refused, select Edit, correct the flagged override or confirm the flow's status on API Testing: Flows, then select Save.
- Expect: The dialog saves the corrected configuration and closes.
Verify: A subsequent run, via Run now or the next cron fire, completes without a Failed badge appearing in the Last Run column.
Steps
Step 1
Open Schedules under API Testing.
Expected result: The Schedules list loads showing the existing schedule, Weekday API smoke (07:00), with its Flow, Cron, Timezone, Enabled state, Next Run, and Last Run columns.
This list is where you review, create, and manage every cron-based trigger for your API flows.
- Add Schedule opens the dialog to create a new schedule.
- The Enabled column (checkbox plus On/Off text) is a clickable toggle, not plain text.
-
Last Run shows a red Failed badge beneath the timestamp when the most recent fire did not succeed.
Field reference
| Field | Purpose | Format / Validation | Required | Default |
|---|---|---|---|---|
| Name | Identifies the schedule in the list and in alert notifications. Use a descriptive name, such as the flow plus its cadence, so you can tell schedules apart at a glance. | Free text | Yes | - |
| Flow | The API flow this schedule triggers. Only an Active flow fires on its cron cadence; a Draft flow accepts the schedule but it won't fire until you commit a revision on API Testing: Flows, and an Archived flow's schedules never fire. | Dropdown selection of flows | Yes | - |
| Cron expression | Sets how often the schedule fires, written as 5 fields (minute hour day month weekday). A tighter pattern such as */5 * * * * fires every 5 minutes for fast feedback but adds load and alert noise; a narrower pattern such as 0 7 * * 1-5 fires once a day on weekdays only. Cron preset buttons can fill in a common pattern for you. | 5-field cron string: minute hour day month weekday | Yes | - |
| Timezone (IANA) | The zone the cron expression is evaluated in. Leave it blank to run in the API process's own local zone, shown resolved once saved (for example as server local on the appliance). Set an IANA zone such as Europe/Amsterdam to keep fire times aligned to that region's hours regardless of where the server runs. | IANA timezone name | No | blank (server local zone) |
| Environment override | Runs this schedule's flow against a different environment than the flow's own default, for example to schedule a staging check on a different cadence than production without duplicating the flow. | Dropdown selection of environments | No | the flow's own environment |
| Auth profile override | Runs this schedule using a different auth profile than the flow's default, for example a dedicated service account for unattended runs. | Dropdown selection of auth profiles | No | the flow's own auth profile |
| Enabled | Turns this schedule's automatic cron firing on or off. This mirrors the Enabled toggle shown in the table. | Checkbox (on/off) | No | on |
| Debug mode (breakpoints + extra capture) | When on, a scheduled run honors any breakpoints set on the flow and captures extra diagnostic data, useful while investigating a failure. Leave it off for routine runs since it adds overhead. | Checkbox (on/off) | No | off |
| Alert profiles (Testing scope) | Selects which Testing-scope alert profiles notify you about this schedule's run outcomes. Profiles themselves are created on Alerting: Profiles and reachable here with the Alerting → Profiles link. | List of checkboxes, one per alert profile | No | none selected |
| Retry on failure | - | Checkbox (on/off) | No | off |
| Max retries (0 to 5) | Caps how many automatic retries a failed run gets. A higher value gives a flaky endpoint more chances to succeed before you're alerted; a lower value, or 0, reports the failure sooner. | Number, 0 to 5 | No | - |
| Retry delay (seconds) | Sets how long to wait between automatic retries. A longer delay gives a transient outage more time to clear before the next attempt; a shorter delay gets a result faster but may hit the same failure again immediately. | Number of seconds | No | - |
Column reference
| Column | What it shows | How to read it |
|---|---|---|
| Name | Shows the schedule's name as set when it was created or last edited. | Identifies the schedule in the list; select its row's Edit icon to see or change the full configuration. |
| Flow | Shows which API flow this schedule triggers. | Names the flow that fires; check API Testing: Flows if you need to confirm that flow's status (Draft, Active, Archived). |
| Cron | Shows the schedule's cron expression. | Read as minute hour day month weekday; for example 0 7 * * 1-5 means 7:00 AM every Monday through Friday. |
| Timezone | Shows the IANA zone the cron is evaluated in. | A specific zone name here confirms the schedule uses that zone instead of the server's local zone. |
| Enabled | Shows whether the schedule is active. On means it fires automatically on its cron cadence; Off means cron firing is suspended until switched back on. | Select the toggle to flip it between On and Off; the change applies immediately, no separate save needed. |
| Next Run | Shows the next time this schedule is due to fire. | Displayed in the module's configured timezone (see the Times in indicator at the top of the page); hover the timestamp for the exact UTC time. |
| Last Run | Shows the timestamp of the most recent fire and, when relevant, a colored outcome badge beneath it. | A red Failed badge means that fire did not complete successfully; open Edit or check API Testing: Run History to investigate. Other noted outcomes are queued and skipped, which mark a fire the scheduler made late, for example because the API was offline at the due time; the next on-time fire or a Run now clears the marker. |
| Actions | Holds the per-row Edit and Delete icons, and Run now where your role allows it. | A disabled icon still appears in place, with a tooltip explaining why your role cannot use it, rather than being hidden. |
Controls reference
Add Schedule
Opens a dialog to create a new schedule with name, flow, cron expression, and optional overrides, alerts, and retry settings.
When to use: When you want to automate a new recurring run of an API flow.
Side effects: Mutating once you select Save: adds a new row to the table. Only shown to a role holding the grant to create schedules.
Enabled toggle (On / Off)
Switches a schedule's automatic cron firing on or off.
When to use: To pause automated runs temporarily, for example during planned downtime, without losing the schedule's configuration.
Side effects: Mutating: flips the Enabled state immediately on click. Disabled, with a tooltip explaining why, for a role without the grant to modify schedules.
Edit / View
Opens the schedule dialog pre-filled with its current configuration. The dialog title and editability depend on your role: Edit for write access, View (read-only) otherwise.
When to use: To change cron, overrides, debug mode, alert profiles, or retries, the only place these settings appear, or to inspect a read-only schedule's configuration.
Side effects: Read-only until you select Save, which then mutates the schedule.
Delete
Opens a confirmation dialog to delete the schedule.
When to use: To remove a schedule you no longer need.
Side effects: Destructive once confirmed with Delete schedule: the schedule is permanently removed and stops firing. Disabled, with a tooltip explaining why, for a role without the grant.
Run now
Fires the schedule's flow immediately, ignoring the cron cadence.
Side effects: Mutating: starts a flow run right away, recorded like any other run. Refused if the schedule's environment or auth override is invalid, if the flow is not Active, or if your role cannot run schedules.
Save
Validates and persists the fields in the schedule dialog.
When to use: After filling in or changing a schedule's configuration in the Add Schedule or Edit dialog.
Side effects: Mutating: creates or updates the schedule row and closes the dialog. Blocked by validation until Name and Cron expression are filled in.
Delete schedule
Confirms permanent deletion of the schedule from the delete confirmation dialog.
When to use: After selecting Delete and deciding you do want to remove the schedule.
Side effects: Destructive and irreversible: the schedule is removed from the table and stops firing.
Retry
Reattempts to load the schedules list after a failed read.
When to use: When the page shows Couldn't load the schedules instead of the table.
Side effects: Read-only: retries the data fetch without changing any schedule.
Show all
Clears a flow filter so the table lists schedules for every flow instead of just one.
When to use: When you arrived here filtered to a single flow's schedules (shown as Filtered to flow) and want to see all schedules.
Side effects: Read-only: changes which rows are shown, no data is modified.
Alerting → Profiles
Navigates to the Alerting Profiles page from inside the schedule dialog.
When to use: When you need to create or edit an alert profile before you can select it under Alert profiles (Testing scope).
Side effects: Read-only navigation: leaves the open dialog.
Cron presets
Fills the Cron expression field with a common preset pattern.
When to use: To set a standard cadence quickly without hand-writing cron syntax.
Side effects: Mutating only within the open, unsaved dialog: overwrites whatever was typed in Cron expression.
Verify the result
After you save a schedule, it appears as a new row in the Schedules table with the Name, Flow, Cron, and Timezone you entered, Enabled set to On, and a Next Run timestamp calculated from the cron expression and timezone. If you edited an existing schedule, the same row reflects your changes as soon as Save closes the dialog. If you don't see the row you expect, confirm Save wasn't blocked by the Name is required. or Cron expression is required. validation messages. If a schedule exists but never fires, check that its Flow is Active rather than Draft or Archived, since only an Active flow's schedules fire on their cron cadence.
Troubleshooting
- Symptom: A new schedule never fires even though Enabled is On. Fix: Confirm the target flow has at least one committed revision; a Draft flow accepts a schedule but only fires once you commit a revision on API Testing: Flows.
- Symptom: Last Run keeps showing a red Failed badge. Fix: Select Edit on the schedule and check Environment override and Auth profile override; an invalid override causes every fire to fail until you correct it.
- Symptom: Add Schedule or a row's Edit/Delete icons are missing or grayed out. Fix: Hover the disabled icon to read the tooltip; your role likely lacks the grant to create or modify schedules, so request access through Operations: Permissions.
- Symptom: Run now reports a refusal naming nodes that can't run, but the message seems to stop mid-list. Fix: The refusal text can be cut off after about 400 characters; check API Testing: Run History for the complete list of affected nodes and reasons.
- Symptom: A schedule's Next Run is later than expected, or the row's timezone looks wrong. Fix: Check the Timezone field; a blank value runs in the server's local zone rather than the zone shown in the Times in indicator at the top of the page.
- Symptom: The page shows Couldn't load the schedules instead of the table. Fix: Select Retry to reattempt the read; if it keeps failing, this is a connectivity issue, not an empty schedule list.
Related articles
- Prerequisite: API Testing: Flows - a schedule must target a flow that's already created and committed there
- Prerequisite: API Testing: Environments - supplies the environments available for the Environment override field
- Prerequisite: API Testing: Auth Profiles - supplies the auth profiles available for the Auth profile override field
- Prerequisite: Alerting: Profiles - Testing-scope alert profiles attached to a schedule are created and managed there
- Next step: API Testing: Run History - every scheduled or Run now fire is recorded there for review
- See also: Configuration: API Testing: Retention - controls how long scheduled run records are kept before they're purged