create_scheduled_run

Create a new scheduled recurring model run for a project. The schedule automatically enqueues model executions on the given cron cadence. Resulting runs appear in list_runs, get_run, get_run_output, and compare_runs.

Supply idempotency_key to safely retry without creating duplicate schedules.

Parameters

Name	Type	Required	Default	Description
project_name	str	Yes	—	Target project name.
cadence	str	Yes	—	5-field UTC cron expression. Minimum interval: 15 minutes.
model_name	str | None	No	None	Model file stem to run (e.g. forecast). Omit for project-level runs (run.py).
branch	str | None	No	None	Git branch to run on. Omit for the project default branch.
idempotency_key	str | None	No	None	Unique key for safe retry. Requests with the same key within 24 hours return the original result.

Cadence format

Standard 5-field UTC cron: minute hour day_of_month month day_of_week

Example	Meaning
0 8 * * 1	Every Monday at 08:00 UTC
0 0 1 * *	First day of each month at midnight UTC
*/30 * * * *	Every 30 minutes
0,15,30,45 * * * *	Every 15 minutes

Minimum interval is 15 minutes. All times are UTC.

Returns

Returns a structured object. Top-level fields:

• schedule (object) — the created schedule summary (see list_scheduled_runs for field descriptions)
• message (string) — confirmation with next run timestamp
• _meta (object \| null) — metadata (null for normal creates)

Example

Tool Call

{
  "name": "create_scheduled_run",
  "arguments": {
    "project_name": "forecasts",
    "cadence": "0 8 * * 1"
  }
}

Response

{
  "schedule": {
    "schedule_id": "20202020-2020-2020-2020-202020202020",
    "project_name": "forecasts",
    "model_name": null,
    "branch": null,
    "cadence": "0 8 * * 1",
    "enabled": true,
    "next_run_at": "2026-05-12T08:00:00+00:00",
    "last_run_at": null,
    "last_run_id": null,
    "last_run_status": null,
    "consecutive_failure_count": 0,
    "created_at": "2026-05-09T10:00:00+00:00"
  },
  "message": "Schedule created. Next run at 2026-05-12T08:00:00+00:00 UTC.",
  "_meta": null
}

Notes

• Module: Scheduled Runs
• Requires authentication via API token or Auth0 JWT.
• Use list_scheduled_runs to view existing schedules.
• Use update_scheduled_run to pause or modify an existing schedule.
• Use delete_scheduled_run to remove a schedule.