API Testing: Schedules
Overview
Use this page to create and manage cron schedules that run API flows automatically. A schedule pairs an API flow with a cron expression so the flow fires on its own at defined times, for example every weekday morning, instead of someone starting it manually with Run Test. It gives you one place to confirm those unattended runs are actually succeeding.
A schedule always points at a flow already built and committed in API Testing: Flows: a Draft flow accepts a schedule but it only fires after a revision is committed, and an Archived flow never fires again. Optional overrides point it at a different environment or credential set, and Testing-scope alert profiles from Alerting: Profiles notify you on failure. Every fire posts its outcome to API Testing: Run History.
From this page you add, edit, enable, disable, or delete schedules, trigger an out-of-cycle run with Run now, and read each row's Next Run and Last Run to see whether it's on track or needs attention.
Key concepts
- Schedule - A cron-based rule that runs a specific API flow automatically at defined times, independent of a manual run. (related: API Testing: Flows)
- Cron expression - A five-field pattern (minute hour day month weekday) that defines exactly when a schedule fires.
- Flow state (Draft / Active / Archived) - Whether the flow a schedule points at can currently fire: a Draft flow accepts a schedule but only fires once a revision is committed, and an Archived flow never fires again. (related: API Testing: Flows)
- Environment override - A schedule-specific target environment that replaces the flow's own default environment for that schedule's runs only. (related: API Testing: Environments)
- Auth profile override - A schedule-specific set of credentials that replaces the flow's own default auth profile for that schedule's runs only. (related: API Testing: Auth Profiles)
When to use it
- You want an API flow to run on a recurring cadence (daily smoke test, hourly health check) without someone starting it manually.
- You need to check whether a scheduled run succeeded or failed before investigating further.
- You want to pause a recurring run temporarily without deleting its configuration.
- You need to trigger an out-of-cycle run right now, ignoring the cron, to retest a fix.
- You need one schedule to hit a different environment or use different credentials than the flow's own default.
- You want failures on a recurring run to notify the right people automatically.
Before you begin
- An API flow created and committed (not left in Draft) in API Testing: Flows, since a schedule accepts a Draft flow but won't fire it until a revision is committed.
- Role grants that permit creating or editing schedules; without them, Add Schedule is not shown and row actions appear disabled with a tooltip explaining why.
- An environment defined in API Testing: Environments if this schedule needs to target something other than the flow's default environment.
- An auth profile defined in API Testing: Auth Profiles if this schedule needs to authenticate differently than the flow's default.
- An alert profile created in Alerting: Profiles if you want this schedule's failures to trigger a notification.
Common workflows
Create a new cron schedule for an API flow
Persona: API test operator
- Select Add Schedule.
- Expect: An empty schedule form opens with Name, Flow, Cron expression, and Timezone fields.
- Enter a Name, choose the Flow to run, and enter a Cron expression such as 0 7 * * 1-5 (or select a preset).
- Expect: The fields populate with your entries; leaving Name or Cron expression blank shows a required-field message.
- Select Save.
- Expect: The form closes and the new schedule appears as a row with Enabled On and a calculated Next Run time.
Verify: The new row shows the Cron and Next Run you set. Once that time passes, the flow fires on its own and the outcome appears in the Last Run cell and in API Testing: Run History.
Pause a schedule without deleting it
Persona: API test operator doing maintenance
- Select the On toggle in the Enabled column for the schedule you want to pause.
- Expect: The toggle switches state immediately; the row no longer fires on its cron.
Verify: The Enabled column reads Off for that row, confirming the schedule is paused until you switch it back on.
Investigate and retry a failed scheduled run
Persona: API test operator
- Open the row whose Last Run shows the Failed badge and select the pencil icon.
- Expect: The schedule's form opens (read-only as View if your role lacks edit grants), showing its environment and auth profile overrides and retry settings.
- Select Run now.
- Expect: The flow fires immediately regardless of the cron, and the Last Run cell updates once the run completes.
Verify: The Last Run cell replaces the Failed badge with the new run's timestamp and outcome.
Steps
Step 1
Open the Schedules page under API Testing.
Expected result: The table loads showing each configured schedule with its Flow, Cron, Timezone, Enabled state, Next Run, and Last Run, and a Credentials expiring notification banner appears in the top-right flagging a token nearing expiry.
This is the starting point for checking whether your scheduled API flow runs are firing on time and succeeding, before you create, edit, or disable any schedule.
- The Credentials expiring banner names the expiring token and the credential profile to reissue it under; select the X to dismiss it.
- The Last Run cell's Failed badge on the Weekday API smoke (07:00) row flags a run that didn't succeed.
- The Times in chip in the header shows the timezone used for Next Run and Last Run timestamps.
Field reference
| Field | Purpose | Format / Validation | Required | Default |
|---|---|---|---|---|
| Name | Identifies the schedule in the list and in notifications, separate from the Flow's own name, so you can tell multiple schedules on the same flow apart. | free text | Yes | - |
| Flow | Chooses which API flow this schedule runs. Pick an Active flow; Draft and Archived flows accept the selection but never actually fire it. | dropdown, lists readable flows | Yes | - |
| Cron expression | Defines exactly when the schedule fires, as five fields (minute hour day month weekday). A narrow expression (one weekday, one hour) fires rarely and is easy to reason about; a wildcard-heavy expression (every few minutes) fires often and produces more Run History entries and more alert noise if a step is failing. | cron syntax, 5 fields | Yes | - |
| Timezone (IANA) | Sets which timezone the cron fields are evaluated in. Leave it blank to run in the API process's own local zone; set an explicit IANA zone so the schedule keeps firing at the same local time across daylight-saving changes. | IANA timezone name | No | blank = server local zone (resolved and displayed, e.g. "UTC (server local)") |
| Environment override | Points this schedule at a different target environment than the flow's own default, for example to run one schedule against staging while the flow's default points at production. Leave blank to inherit the flow's environment. | dropdown | No | blank = flow's default environment |
| Auth profile override | Points this schedule at different credentials than the flow's own default, useful when one schedule must authenticate as a different account. Leave blank to inherit the flow's auth profile. | dropdown | No | blank = flow's default auth profile |
| Enabled | Controls whether the cron actually fires. Clear it to keep the schedule configured but inactive without deleting it; this is the same state as the row-level toggle. | checkbox | No | On |
| Debug mode (breakpoints + extra capture) | Turns on breakpoints and extra capture for this schedule's runs. Turn it on while diagnosing a failing flow; leave it off for routine runs since extra capture adds overhead you don't normally need. | checkbox | No | Off |
| Alert profiles (Testing scope) | Attaches one or more Testing-scope alert profiles so a failed or recovered run notifies the right people. Attach none to leave the schedule silent and rely on checking Last Run manually. | checkbox list | No | none attached |
| Retry on failure | Turn it on for flaky or network-sensitive flows; leave it off if a failure should surface immediately for investigation. | checkbox | No | Off |
| Max retries (0-5) | Caps how many automatic retries Retry on failure performs. A higher value gives a flaky flow more chances to succeed before a failure notification goes out, at the cost of delaying that notification and adding Run History entries per fire. | number, 0-5 | No | - |
| Retry delay (seconds) | Sets how long the schedule waits between a failed attempt and its automatic retry. A longer delay gives a transient issue more time to clear before retrying; a shorter delay gets a result sooner but is more likely to hit the same transient failure again. | number, seconds | No | - |
Column reference
| Column | What it shows | How to read it |
|---|---|---|
| Name | Identifies the schedule in the table. | Read alongside Flow to tell which schedule belongs to which flow when a flow has more than one. |
| Flow | Names the API flow this schedule runs. | Open API Testing: Flows to check this flow's current state if the schedule isn't firing. |
| Cron | Shows the raw cron expression for this schedule. | Read together with Timezone to know the actual local fire time. |
| Timezone | Shows the zone the Cron field is evaluated in for this schedule. | Compare it to the Times in chip in the page header if the two differ. |
| Enabled | Shows whether the cron is currently active. | On means the schedule will fire at its Next Run; Off means it is paused and will not fire until switched back on. Select the toggle to flip it. |
| Next Run | Shows when the schedule is calculated to fire next. | Shown in the timezone named by the Times in chip in the page header; hover for the raw UTC value. |
| Last Run | Shows the timestamp and outcome of the most recent fire. | A Failed badge means that run didn't complete successfully; check the flow, environment override, or auth profile override before the next scheduled fire. |
| Actions | Row-level controls for this schedule. | Toggle Enabled, Run now, Edit (or View if your role can't change schedules), and Delete; a disabled icon with a tooltip means your role's grants don't permit that action. |
Controls reference
Dismiss notification
Closes the Credentials expiring banner.
When to use: After you've read which credential is expiring and don't need the reminder on screen.
Side effects: Read-only; hides the banner for this session, no data changes.
Show all
Clears a filter to a single flow and reloads the full schedule list.
When to use: When you arrived at this page filtered to one flow (for example from a flow's details) and want to see every schedule again.
Side effects: Read-only; changes which rows are shown, no data changes.
Add Schedule
Opens an empty schedule form (Name, Flow, Cron expression, Timezone, overrides, retries, alert profiles).
When to use: When you need a new recurring or on-demand cron rule for an API flow.
Side effects: Read-only until you select Save in the form; only drawn for a role whose grants permit creating schedules.
Retry
When to use: When the page shows "Couldn't load the schedules" instead of the table.
Side effects: Read-only; re-runs the list request, no data changes.
Enabled toggle (On / click to disable)
Flips a schedule between active and paused.
When to use: To pause a recurring schedule temporarily without deleting it, or to reactivate a paused one.
Side effects: Mutating; takes effect immediately on selection, no confirmation step. While Off, the cron does not fire.
Run now
Fires the schedule's flow immediately, ignoring the cron.
When to use: To retest a fix out of cycle, or to re-run a schedule whose Last Run shows Failed.
Side effects: Mutating; queues a real run against the schedule's environment and auth (override or default). Disabled with a tooltip if your role can't run schedules or if the flow's current revision refuses that node type.
Edit (pencil)
Opens the schedule's form showing Name, Flow, Cron expression, Timezone, environment and auth overrides, Enabled, Debug mode, Alert profiles, Retry on failure, Max retries, and Retry delay.
When to use: To change any setting on an existing schedule, or to review one when you only have read access.
Side effects: Read-only until Save is selected. A role that can read but not change schedules gets the same dialog labeled View instead of Edit, with inputs disabled.
Delete (trash)
Opens a delete confirmation for the schedule.
When to use: When a schedule is no longer needed.
Side effects: Opens a confirm dialog only; the schedule is removed once you confirm inside it. Disabled with a tooltip if your role can't delete schedules.
Cron preset buttons
Fills the Cron expression field in the form with a common pattern.
When to use: When you want a standard cadence without typing the five cron fields by hand.
Side effects: Mutating to the form only; overwrites any value currently typed in Cron expression. Nothing is saved until you select Save.
Alerting → Profiles
Opens Alerting: Profiles.
When to use: When the alert profile you want to attach doesn't exist yet.
Side effects: Read-only navigation link; leaves the current schedule form.
Save
Persists the schedule you're creating or editing.
When to use: After filling in or changing the schedule's fields.
Side effects: Mutating; writes the schedule, which then appears (or updates) as a row in the table.
Delete schedule
Confirms removal of the schedule.
When to use: After selecting Delete, once you're sure the schedule should go.
Side effects: Mutating and destructive; the schedule and its row are removed and it stops firing.
Verify the result
The Schedules table lists each cron schedule with its Flow, Cron expression, Timezone, Enabled state, Next Run, and Last Run outcome visible at a glance. A newly created or edited schedule appears as a row with Enabled On and a populated Next Run time in the header's configured timezone. If a schedule's last fire failed, the Last Run cell shows a Failed badge instead of a clean timestamp, telling you to check the flow, environment override, or auth profile override before the next scheduled fire. If an expected schedule doesn't appear, confirm you selected Save (Name and Cron expression are both required) and that the target flow is Active, not Draft or Archived.
Troubleshooting
- Symptom: A schedule never fires even though Enabled shows On. Fix: Check the flow's state in API Testing: Flows; a Draft flow accepts a schedule but only fires once a revision is committed, and an Archived flow never fires again.
- Symptom: Run now is disabled with a tooltip. Fix: Your role doesn't have grants to run schedules, or the flow's current revision refuses that node type; confirm your permissions or check the flow in API Testing: Flows.
- Symptom: Last Run shows a Failed badge. Fix: Open Edit to check the schedule's environment and auth profile overrides, and confirm the credential referenced hasn't expired, as flagged by the Credentials expiring banner.
- Symptom: The Edit dialog opens read-only with no Save button. Fix: Your role can view the schedule's overrides, debug mode, alert profiles, and retry settings but not change them; ask an admin with schedule-write grants.
- Symptom: Saving a new schedule shows "Name is required." or "Cron expression is required." Fix: Both fields are mandatory; enter a Name and a valid five-field Cron expression before selecting Save.
- Symptom: The page shows "Couldn't load the schedules" instead of the table. Fix: Select Retry; the schedule list loads independently of flow, environment, and auth profile name lookups, so a retry often succeeds even if those are still failing.
Related articles
- Prerequisite: API Testing: Flows - a schedule always runs an existing, committed flow
- Prerequisite: API Testing: Environments - defines the environments selectable in a schedule's Environment override
- Prerequisite: API Testing: Auth Profiles - defines the credentials selectable in a schedule's Auth profile override
- Prerequisite: Alerting: Profiles - Testing-scope alert profiles attached to a schedule are created here
- Next step: API Testing: Run History - every scheduled or Run now fire posts its result here for review
- See also: Configuration: Credential Profiles - reissue an expiring credential the Credentials expiring banner references