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
`persona_id`	uuid	body	No	Default persona for runs
`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

persona_id

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 user journey to schedule

Parameters

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

Status Codes

Code	Description
`201`	Item added
`401`	Unauthorized
`404`	Schedule not found

API Key

id *

journey_id *

priority

cURL

Response

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

Remove user journey from schedule

Parameters

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

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