⌘K

Scheduled Debates

Automatically run debates on a recurring schedule — daily, weekly, or monthly — using AskVerdict's scheduled debate system.

7 min read

Scheduled Debates let you define a debate question once and have it run automatically on a recurring basis — every day, every week, or every month. Results accumulate in your debate history just like manually triggered debates, with full outcome tracking support.

Common use cases include daily team standup debates, weekly retrospective analysis, and recurring market or technology reviews.

How Scheduling Works

When you create a scheduled debate, AskVerdict:

Computes the nextRunAt timestamp based on your frequency, timeOfDay, and optional dayOfWeek / dayOfMonth configuration
Stores the schedule as an active record in the system
Runs a background task runner that polls for schedules where nextRunAt <= now and active = true
After each run, increments runCount, updates lastRunAt, and computes the next nextRunAt

Timezone handling

All scheduling is computed in UTC. The timezone field is stored for display purposes and future timezone-aware scheduling. When specifying timeOfDay, always use UTC time.

Creating a Schedule

POST/api/scheduled-debates

Create a new recurring debate schedule

bash

curl -X POST https://api.askverdict.ai/api/scheduled-debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the most impactful engineering task the team should focus on today?",
    "mode": "fast",
    "frequency": "daily",
    "timeOfDay": "08:30",
    "timezone": "America/New_York"
  }'

Name	Type	Required	Description
`question`	`string`	Required	The debate question to run on each occurrence
`frequency`	`"daily" \| "weekly" \| "monthly"`	Required	How often to run the debate
`mode`	`"fast" \| "balanced" \| "thorough"`	Optional	Debate depth mode. Defaults to your account's default mode. Fast is recommended for frequent schedules.
`context`	`string`	Optional	Additional context injected into every run of this scheduled debate
`timeOfDay`	`string`	Optional	Time in UTC to run the debate, formatted as HH:MM. Default: 09:00
`timezone`	`string`	Optional	IANA timezone name for display purposes (e.g. America/New_York). Scheduling is UTC-based. Default: UTC
`dayOfWeek`	`number`	Optional	Required for weekly frequency. 0 = Sunday, 1 = Monday, ..., 6 = Saturday
`dayOfMonth`	`number`	Optional	Required for monthly frequency. 1–31. If the target day does not exist in a given month (e.g. 31 in February), the run is skipped to the next month.
`maxRuns`	`number`	Optional	Maximum number of times to run. Null (default) means unlimited.

Schedule Examples

Daily Standup Debate

Run a team focus question every weekday morning at 9 AM UTC:

bash

curl -X POST https://api.askverdict.ai/api/scheduled-debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What should be the team'\''s top priority today?",
    "mode": "fast",
    "frequency": "daily",
    "timeOfDay": "09:00",
    "timezone": "UTC"
  }'

Use mode: "fast" for daily schedules. Fast mode uses 1 credit per run and completes in under 10 seconds — appropriate for lightweight recurring questions.

Weekly Architecture Review

Run a technology assessment every Monday at 10 AM UTC:

bash

curl -X POST https://api.askverdict.ai/api/scheduled-debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the highest-risk technical debt item in our codebase this week?",
    "mode": "balanced",
    "frequency": "weekly",
    "dayOfWeek": 1,
    "timeOfDay": "10:00",
    "context": "We run a TypeScript monorepo with Hono + Next.js. Current headcount: 6 engineers."
  }'

The context field is injected into every run of the scheduled debate. Use it to provide standing background information that does not change between runs.

Monthly Strategy Review

Run a strategy evaluation on the first of each month at 14:00 UTC, for a maximum of 12 runs (one year):

bash

curl -X POST https://api.askverdict.ai/api/scheduled-debates \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What product initiative should we prioritize next month?",
    "mode": "thorough",
    "frequency": "monthly",
    "dayOfMonth": 1,
    "timeOfDay": "14:00",
    "maxRuns": 12
  }'

Listing Schedules

GET/api/scheduled-debates

List your recurring debate schedules

bash

# List all schedules
curl "https://api.askverdict.ai/api/scheduled-debates" \
  -H "Authorization: Bearer vrd_your_api_key"
 
# List only active schedules
curl "https://api.askverdict.ai/api/scheduled-debates?active=true" \
  -H "Authorization: Bearer vrd_your_api_key"
 
# Paginate
curl "https://api.askverdict.ai/api/scheduled-debates?page=2&limit=10" \
  -H "Authorization: Bearer vrd_your_api_key"

Name	Type	Required	Description
`page`	`number`	Optional	Page number (default: 1)
`limit`	`number`	Optional	Results per page (default: 20)
`active`	`boolean`	Optional	Filter by active status. Omit to return all schedules.

Updating a Schedule

PATCH/api/scheduled-debates/:id

Update a schedule's question, timing, or active status

All fields are optional. Only the fields you provide are updated. When any scheduling field changes (frequency, dayOfWeek, dayOfMonth, timeOfDay, timezone), the nextRunAt timestamp is automatically recomputed.

bash

# Pause a schedule
curl -X PATCH https://api.askverdict.ai/api/scheduled-debates/scd_01j9abc456 \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
 
# Change the question and reschedule to Fridays
curl -X PATCH https://api.askverdict.ai/api/scheduled-debates/scd_01j9abc456 \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What were the key learnings from this week?",
    "dayOfWeek": 5,
    "timeOfDay": "16:00"
  }'

Name	Type	Required	Description
`question`	`string`	Optional	Updated debate question
`mode`	`"fast" \| "balanced" \| "thorough"`	Optional	Updated debate mode
`context`	`string`	Optional	Updated standing context
`frequency`	`"daily" \| "weekly" \| "monthly"`	Optional	Updated frequency — triggers nextRunAt recomputation
`dayOfWeek`	`number`	Optional	Updated day of week for weekly schedules (0–6)
`dayOfMonth`	`number`	Optional	Updated day of month for monthly schedules (1–31)
`timeOfDay`	`string`	Optional	Updated time in HH:MM UTC
`timezone`	`string`	Optional	Updated display timezone
`active`	`boolean`	Optional	Set to false to pause without deleting
`maxRuns`	`number \| null`	Optional	Updated run limit. Pass null to make unlimited.

Getting a Single Schedule

GET/api/scheduled-debates/:id

Get a single scheduled debate by ID

bash

curl https://api.askverdict.ai/api/scheduled-debates/scd_01j9abc456 \
  -H "Authorization: Bearer vrd_your_api_key"

The response includes runCount and lastRunAt, which let you verify that runs are occurring as expected.

Deleting a Schedule

DELETE/api/scheduled-debates/:id

Permanently delete a scheduled debate

bash

curl -X DELETE https://api.askverdict.ai/api/scheduled-debates/scd_01j9abc456 \
  -H "Authorization: Bearer vrd_your_api_key"

Deleting a schedule does not delete the debates that were already run — those remain in your debate history.

To temporarily stop a schedule without losing its configuration, set active: false via PATCH instead of deleting it.

`nextRunAt` Computation Rules

The next run time is always computed forward from the current time. The rules by frequency:

Daily

The next occurrence of timeOfDay in UTC. If that time has already passed today, the next run is tomorrow at the same time.

Current time (UTC)	timeOfDay	nextRunAt
2026-02-20 10:30	09:00	2026-02-21 09:00
2026-02-20 08:00	09:00	2026-02-20 09:00

Weekly

The next occurrence of dayOfWeek at timeOfDay. If today is the target day but the time has passed, the next run is one week from now.

Today (UTC)	dayOfWeek	timeOfDay	nextRunAt
Wednesday 14:00	1 (Monday)	10:00	Next Monday 10:00
Monday 08:00	1 (Monday)	10:00	Today (Monday) 10:00
Monday 11:00	1 (Monday)	10:00	Next Monday 10:00

Monthly

The next occurrence of dayOfMonth at timeOfDay. If the target day has not yet occurred this month and the time is in the future, it runs this month. Otherwise it runs next month.

If dayOfMonth is set to 31 and the current month has fewer than 31 days (e.g. February), the schedule skips to the following month that has 31 days.

`maxRuns` and Auto-Deactivation

When maxRuns is set, the schedule automatically sets active = false after runCount reaches maxRuns. The schedule record remains visible in your list but no further runs are triggered.

bash

# Check if a schedule has been auto-deactivated
curl https://api.askverdict.ai/api/scheduled-debates/scd_01j9abc456 \
  -H "Authorization: Bearer vrd_your_api_key"
 
# Response example for a completed maxRuns schedule:
# {
#   "schedule": {
#     "active": false,
#     "runCount": 12,
#     "maxRuns": 12,
#     "lastRunAt": "2027-01-01T14:00:00Z",
#     "nextRunAt": null
#   }
# }

Credit Usage

Each scheduled run consumes credits just like a manually triggered debate:

Mode	Credits per run
`fast`	1 credit
`balanced`	3 credits
`thorough`	8 credits

Ensure your account has sufficient credits before creating high-frequency schedules. If a run fails due to insufficient credits, it is skipped and nextRunAt advances to the following scheduled time.

BYOK plans do not consume AskVerdict credits, but your provider API key must have sufficient quota. Runs that fail due to provider errors are retried once after a short delay before being skipped.

Outcome Tracking with Schedules

Each run of a scheduled debate creates a standalone debate record with a new debate ID. You can track outcomes for each run independently, building a longitudinal record of how a recurring decision evolves over time.

To find all debates generated by a specific schedule, search your debate history with the schedule question as a filter:

bash

curl "https://api.askverdict.ai/api/debates?search=most+impactful+engineering+task" \
  -H "Authorization: Bearer vrd_your_api_key"

See Decision Intelligence for full outcome tracking documentation.

Was this page helpful?

PreviousSSE Streaming Events NextMigration & Breaking Changes

Scheduled Debates

How Scheduling Works

Creating a Schedule

Schedule Examples

Daily Standup Debate

Weekly Architecture Review

Monthly Strategy Review

Listing Schedules

Updating a Schedule

Getting a Single Schedule

Deleting a Schedule

`nextRunAt` Computation Rules

Daily

Weekly

Monthly

`maxRuns` and Auto-Deactivation

Credit Usage

Outcome Tracking with Schedules

Product

Company

Use Cases

Teams

Content

Developer

Policies

Agreements