OctoPerf — Scheduling scenarios

OctoPerf can fire a load-test scenario on a schedule — either once at a future moment, or recurrently via a cron expression. Every fire consumes credits exactly like a manual `run_scenario`, so a daily cron drains the subscription every day until you pause or delete it.

When this applies

• The user wants a scenario to run automatically — overnight batch,

weekly soak test, regression run after a release tag, etc.

• The user is asking about an existing scheduled job — show it, pause

it, change its cadence, delete it.

The pitfalls — read this BEFORE invoking any schedule tool

1. The cron format is Unix 5-field, not Quartz, and it's in UTC

OctoPerf's cron parser is UnixCronTrigger — 5 fields, no seconds, evaluated in UTC on the server. Quartz expressions like 0 0 3 * * ? (6 fields) are rejected with an opaque HTTP 400.

The five fields are:

minute  hour  day-of-month  month  day-of-week
0-59    0-23  1-31           1-12   0-7 (0 and 7 are Sunday)

Use * for "any value". Comma lists (1,15), ranges (1-5) and step values (*/15) work. Day-of-week uses Unix conventions (1=Monday in the documented examples).

2. UTC, not local time — convert explicitly

A user saying "every night at midnight" almost never means UTC. You have to convert their local time to UTC before computing the expression. Examples for Europe/Paris:

Daylight Saving Time is a real concern: a daily Paris cron set in summer will fire one hour off in winter (and vice versa). The user either accepts that drift, or you advise picking a less DST-sensitive slot (e.g. anchor on UTC and tell them when it fires in local time).

When in doubt, ask the user which fixed-UTC slot they want, or use a single-fire schedule_scenario_once with an ISO-8601 offset which is unambiguous.

3. Pre-flight FIRST — a misconfigured cron fires failing runs forever

Before schedule_scenario_*, call get_scenario_matching_plans on the scenario. If it returns an empty list, the scheduled run will fail at startup every single fire until someone notices and disables the job.

mcp__octoperf__get_scenario_matching_plans(scenarioId)

Empty result → flag to the user, run list_active_subscriptions to explain which cap is binding, do not schedule.

A scheduled cron is also more dangerous than a manual run_scenario because:

• The failure is asynchronous (the user might not see it for days)
• The credit cost compounds (1/day × 30 days = 30 credits for nothing)
• The orchestration log is the only diagnostic when the run errored

before producing samples (list_bench_docker_logs)

Steps

1. Decide one-shot vs recurring

• One-shot (schedule_scenario_once) — for "run X at this specific

moment". Takes an ISO-8601 datetime with timezone offset (2026-06-15T03:00:00+02:00) — unambiguous, no timezone math.

• Recurring (schedule_scenario_cron) — for "every N days /

hours / Monday morning / etc.". Requires the Unix 5-field UTC cron.

2. Build the trigger value

For one-shot:

• Take the user's local datetime, write it ISO-8601 with the

appropriate offset for that wall-clock date (mind DST).

• Example: "tomorrow at 6 PM Paris time" on 2026-05-15 = 2026-05-15T18:00:00+02:00.

For recurring:

• Convert the local time of day to UTC for the current DST state.
• Surface the DST caveat to the user if their cadence crosses DST

transitions.

3. Pre-flight + schedule

mcp__octoperf__get_scenario_matching_plans(scenarioId)   # MUST be non-empty
mcp__octoperf__schedule_scenario_once(scenarioId, runAt, name)
# or
mcp__octoperf__schedule_scenario_cron(scenarioId, expression, name)

Always pass an explicit name — empty names make the scheduler view in the OctoPerf UI hard to read.

4. Confirm the next fire time

Both tools return nextRun (epoch-ms). Render it back to the user in their local time so they can sanity-check ("nextRun = 2026-05-15T00:00 Paris ✓" — not "1778796000000"). If it lands on the wrong instant, the UTC conversion is off — fix the cron and re-schedule.

5. Manage existing jobs

mcp__octoperf__list_scheduled_jobs_by_project(projectId)
mcp__octoperf__enable_scheduled_job(jobId)    # re-arms credit-consuming runs
mcp__octoperf__disable_scheduled_job(jobId)   # safe pause, reversible
mcp__octoperf__delete_scheduled_job(jobId)    # destructive — prefer disable

The list returns every job in the project — including the disabled ones. Group by enabled when reporting to the user.

6. Recovery — when a scheduled run silently failed

A scheduled fire that errored before producing samples won't show up in list_bench_reports_by_project like a real run. To audit:

• list_scheduled_jobs_by_project(projectId) → check each job's

nextRun — if a daily cron's nextRun is in the past, something is off (the trigger may be misconfigured).

• For each suspect job, get the recent benchResults of the scenario

(list_bench_reports_by_project filtered on the scenario's id) and check their state via get_bench_result. ERROR-state runs without metrics = the fire happened but the scenario didn't start.

• If you find an ERROR run, follow the octoperf-scenario-diagnosis

step 0 ("did the run even start?") — list_bench_docker_logs on the bench result id is the next step.

Pitfalls

• Don't pass a Quartz expression — it'll be rejected with HTTP 400. Use Unix 5-field.
• Don't forget UTC — every cron expression is evaluated in UTC. A cron typed in local time is silently wrong.
• Don't schedule a scenario you haven't pre-flighted — the cost compounds with the cadence.
• Don't delete to pause — delete_scheduled_job is irreversible. Use disable_scheduled_job and keep the config around.
• Don't ignore DST — a cron that's right in May will be one hour off in November (and vice versa). Mention it to the user when relevant.

See also

• octoperf-scenario-diagnosis — when a scheduled run produced bad metrics or errored before sampling.
• OctoPerf scheduler docs: <https://doc.octoperf.com/runtime/scheduler/>