Schedules

Schedules automate recurring journey execution. Assign journeys to a schedule, set a frequency, and the system runs them on a rotating basis within your agent budget.

Overview

A schedule ties a set of journeys to a recurring cadence. You define when to run (time of day, which days of the week), how often to tick, and a coverage window that determines how urgently each journey needs to be re-run. The system handles the rest.

Schedules are budget-aware. Each tenant has a daily agent budget that limits how many agents can be spawned per day across all schedules. The scheduler uses a scoring system that prioritizes journeys based on staleness (how long since they last ran) and priority (a weight you assign to each schedule item). Journeys that have not run recently are picked first. This means the system automatically rotates through all your journeys even if the daily budget does not allow running all of them in a single tick.

Schedule items

Each schedule contains a list of items. An item is a reference to a journey with a priority weight. Higher priority items are preferred when the budget forces a choice. Each item tracks when it last ran, so the staleness scoring works per-journey.

Email digest

Schedules can be configured to send an email digest after each tick. The digest summarizes the results of all agents that ran and can be set to send always or only when failures occur. Configure recipients and optionally filter by finding severity.

POST /api/v1/schedules

Create a schedule

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	body	Yes	Project ID
`name`	string	body	Yes	Schedule name
`coverage_window_hours`	integer	body	No	Hours within which all journeys must run (default: 120)
`tick_interval_hours`	integer	body	No	Hours between ticks (default: 24)
`daily_budget`	integer	body	No	Max test runs per tick (null = auto)
`run_days`	array	body	No	ISO day numbers to run on (Mon=1..Sun=7). Default: all days. Example: [1,2,3,4,5] for weekdays.
`journey_ids`	array	body	No	Journey IDs to include
`role_id`	uuid	body	No	Default role for runs
`digest_config`	object	body	No	Email digest settings. Example: {"enabled": true, "channels": ["email"], "notify_on": "always", "recipients": ["alice@example.com"], "min_severity": "high"}. min_severity: "critical", "high", "medium", "low" (omit for all).

Status Codes

Code	Description
`201`	Schedule created
`400`	Validation error
`401`	Unauthorized
`404`	Project not found

Response Body

{
  "schedule": {
    "id": "019d4000-0000-7000-0000-000000000000",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "Daily QA sweep",
    "coverage_window_hours": 120,
    "daily_budget": 2,
    "tick_interval_hours": 24,
    "run_days": [1, 2, 3, 4, 5],
    "enabled": true,
    "last_tick_at": null,
    "created_at": "2026-03-31T10:00:00Z",
    "updated_at": "2026-03-31T10:00:00Z"
  },
  "items": []
}

API Key

project_id *

name *

coverage_window_hours

tick_interval_hours

daily_budget

run_days

journey_ids

role_id

digest_config

cURL

Response

GET /api/v1/schedules

List schedules

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	query	No	Filter by project
`limit`	integer	query	No	Page size (default: 20)
`after`	uuid	query	No	Cursor for next page

Status Codes

Code	Description
`200`	OK
`401`	Unauthorized

API Key

project_id

limit

after

cURL

Response

GET /api/v1/schedules/{id}

Get schedule with items and recent runs

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID

Status Codes

Code	Description
`200`	OK
`401`	Unauthorized
`404`	Not found

API Key

id *

cURL

Response

PATCH /api/v1/schedules/{id}

Update schedule

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID
`name`	string	body	No	New name
`enabled`	boolean	body	No	Enable or disable
`coverage_window_hours`	integer	body	No	New coverage window
`tick_interval_hours`	integer	body	No	New tick interval
`daily_budget`	integer	body	No	New budget (null = auto)
`run_days`	array	body	No	ISO day numbers (Mon=1..Sun=7)
`digest_config`	object	body	No	Email digest settings (see Create for shape). Set to null to disable.

Status Codes

Code	Description
`200`	Updated
`401`	Unauthorized
`404`	Not found

API Key

id *

name

enabled

coverage_window_hours

tick_interval_hours

daily_budget

run_days

digest_config

cURL

Response

DELETE /api/v1/schedules/{id}

Delete schedule

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID

Status Codes

Code	Description
`204`	Deleted
`401`	Unauthorized
`404`	Not found

API Key

id *

cURL

Response

POST /api/v1/schedules/{id}/items

Add a user journey or test plan to a schedule

Schedules can carry both user journeys and test plans as items. The request body must specify exactly one of journey_id or test_plan_id; specifying both, or neither, returns 400. The response shape mirrors the kind of item that was added (journey items have a journey_id field; test-plan items have a test_plan_id field).

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID
`journey_id`	uuid	body	No	Journey to add. Mutually exclusive with test_plan_id.
`test_plan_id`	uuid	body	No	Test plan to add. Mutually exclusive with journey_id.
`priority`	integer	body	No	Priority (higher = preferred) (default: 0)

Status Codes

Code	Description
`201`	Item added
`400`	Validation error (e.g. missing or duplicated identifier, item belongs to a different project)
`401`	Unauthorized
`404`	Schedule not found

API Key

id *

journey_id

test_plan_id

priority

cURL

Response

DELETE /api/v1/schedules/{id}/items/{itemId}

Remove a user journey or test plan item from a schedule

Accepts the ID of either a journey item or a test-plan item; the handler dispatches to the right table automatically.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID
`itemId`	uuid	path	Yes	Item ID (journey-item or test-plan-item)

Status Codes

Code	Description
`204`	Removed
`401`	Unauthorized
`404`	Not found

API Key

id *

itemId *

cURL

Response

GET /api/v1/schedules/{id}/runs

List schedule runs (audit trail)

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID

Status Codes

Code	Description
`200`	OK
`401`	Unauthorized
`404`	Not found

API Key

id *

cURL

Response

POST /api/v1/schedules/{id}/trigger

Manually trigger a schedule tick

Runs the scheduling algorithm for this schedule immediately, ignoring last_tick_at.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID

Status Codes

Code	Description
`200`	Triggered
`401`	Unauthorized
`404`	Not found

API Key

id *

cURL

Response

POST /api/v1/schedules/{id}/digest

Send a digest email for this schedule now

Force-sends a digest email summarising the agents from this schedule's most recent triggered runs. Requires digest_config.enabled = true on the schedule. Recipients and severity filters come from digest_config.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID

Status Codes

Code	Description
`200`	Digest dispatched
`400`	Digest is not enabled on this schedule
`401`	Unauthorized
`404`	Not found

API Key

id *

cURL

Response