create_scheduled_run

Create a new scheduled recurring model run for a project. cadence is required: a 5-field UTC cron expression (minute hour day_of_month month day_of_week). Examples: ‘0 8 * * 1’ (every Monday 08:00 UTC), ‘0 0 1 * *’ (monthly). Minimum interval: 15 minutes. All times are UTC. Runs appear in list_runs, get_run, and compare_runs once triggered.

Parameters

Name	Type	Required	Default	Description
project_name	Annotated[str, Field(description='Name of the Bridge Town project.')]	Yes	—
cadence	Annotated[str, Field(description="Cron expression or interval string defining when the run executes (e.g. '0 9 * * 1' for Mondays at 9am UTC).")]	Yes	—
model_name	`Annotated[str	None, Field(description=“Model file to execute on the schedule (without .py extension). Defaults to ‘run’.”)]`	No	None
branch	`Annotated[str	None, Field(description=“Branch to execute the scheduled run from. Defaults to the project’s default branch.”)]`	No	None
idempotency_key	`Annotated[str	None, Field(description=‘Optional idempotency key to prevent duplicate schedules. Re-sending the same key returns the existing schedule instead of creating a duplicate.’)]`	No	None

Returns

Returns a structured object. Top-level fields:

• schedule (object)
• message (string)
• _meta (null)

See the response example below for the full payload shape.

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-04-28T10: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.