Schedules

Schedules let you run reconciliation automatically on a recurring cadence instead of triggering match runs by hand. Each schedule belongs to a reconciliation context and fires on a cron expression, with a minimum interval of five minutes between firings.

What is a schedule?

A schedule is a cron-based trigger attached to a context. When it fires, Matcher starts a COMMIT match run for that context with its rules and sources. The run reconciles only when the context is ACTIVE.

Field	Type	Description
`id`	UUID	Unique identifier for the schedule
`contextId`	UUID	Context this schedule belongs to
`cronExpression`	String	Cron expression defining the frequency (e.g. `0 0 * * *` for daily at midnight)
`enabled`	Boolean	Whether the schedule is active
`lastRunAt`	Timestamp	Time Matcher last dispatched the asynchronous match-run trigger; it does not indicate completion or success (RFC 3339)
`nextRunAt`	Timestamp	Next scheduled run time (RFC 3339)
`createdAt` / `updatedAt`	Timestamp	Creation and last-update timestamps (RFC 3339)

Schedule lifecycle

Schedules support a full CRUD lifecycle under /v1/contexts/{contextId}/schedules.

Action	Method & path
Create schedule	`POST /v1/contexts/{contextId}/schedules`
List schedules	`GET /v1/contexts/{contextId}/schedules`
Retrieve schedule	`GET /v1/contexts/{contextId}/schedules/{scheduleId}`
Update schedule	`PATCH /v1/contexts/{contextId}/schedules/{scheduleId}`
Delete schedule	`DELETE /v1/contexts/{contextId}/schedules/{scheduleId}`

API Reference:

Creating a schedule

Provide a cronExpression. The enabled field defaults to active when omitted.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 0 * * *",
   "enabled": true
 }'

String

required

Cron expression defining the run frequency (1–100 chars), with at least five minutes between firings. Use five fields: minute, hour, day of month, month, and day of week. Matcher rejects a seconds field, macros such as @daily, and per-minute and sub-minute schedules

Boolean

Whether the schedule is active immediately

The response returns the created schedule, including its id, nextRunAt, and timestamps. Listing schedules (GET) returns every schedule for the context, enabled and disabled alike.

Pausing vs. deleting a schedule

When you need to stop a recurring reconciliation, you have two options. Disable the schedule to pause automatic runs while keeping its configuration and history. Re-enabling later is a single call, with no need to recreate it. Update the cron expression, toggle enabled, or both (omitted fields stay unchanged):

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}/schedules/{scheduleId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 6 * * *",
   "enabled": false
 }'

Delete the schedule (DELETE .../schedules/{scheduleId}) only when the cadence is gone for good. Deletion is permanent. To take a break, disable instead.

Best practices

Align cadence with source availability

Schedule runs to fire after all sources for the context have delivered their data for the period. Running before ingestion completes produces avoidable exceptions.

Prefer disabling over deleting

To pause a reconciliation cadence, disable the schedule. It keeps history and configuration, and re-enabling is a single call.

Use explicit cron expressions

Keep cron expressions readable and documented (e.g. 0 0 * * * = daily at 00:00). Matcher evaluates them in UTC.

Overview

Guides

Console

MCP Server

Operations

What is a schedule?

Schedule lifecycle

Creating a schedule

Pausing vs. deleting a schedule

Best practices

Next steps

Contexts and Sources

Generating Reports

​What is a schedule?

​Schedule lifecycle

​Creating a schedule

​Pausing vs. deleting a schedule

​Best practices

​Next steps

Contexts and Sources

Generating Reports

What is a schedule?

Schedule lifecycle

Creating a schedule

Pausing vs. deleting a schedule

Best practices

Next steps