> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedules

> Automate reconciliation runs with cron-based schedules per context, and manage them through a full create, list, retrieve, update, and delete lifecycle.

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, so a context can be reconciled daily, hourly, or on any custom frequency you define.

## What is a schedule?

***

A schedule is a cron-based trigger attached to a context. When it fires, Matcher launches a reconciliation run for that context using its active rules and sources.

| 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 | Last successful run time (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}` |

<Tip>
  API Reference:

  * [Create schedule](/en/reference/matcher/create-schedule)
  * [List schedules](/en/reference/matcher/list-schedules)
  * [Get schedule](/en/reference/matcher/retrieve-schedule)
  * [Update schedule](/en/reference/matcher/update-schedule)
  * [Delete schedule](/en/reference/matcher/delete-schedule)
</Tip>

## Creating a schedule

***

Provide a `cronExpression`; `enabled` defaults to active when omitted.

```bash cURL theme={null}
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
 }'
```

<ParamField path="cronExpression" type="String" required>
  Cron expression defining the run frequency (1–100 chars)
</ParamField>

<ParamField path="enabled" type="Boolean">
  Whether the schedule is active immediately
</ParamField>

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 — and the choice matters.

**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 are left unchanged):

```bash cURL theme={null}
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 simply take a break, disable instead.

## Best practices

***

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Prefer disabling over deleting">
    When pausing a reconciliation cadence, disable the schedule so history and configuration are preserved and re-enabling is a single call.
  </Accordion>

  <Accordion title="Use explicit cron expressions">
    Keep cron expressions readable and documented (e.g. `0 0 * * *` = daily at 00:00). Verify the timezone assumptions for your deployment before relying on a schedule for SLA-sensitive runs.
  </Accordion>
</AccordionGroup>

## Next steps

***

<Card title="Contexts and Sources" icon="folder-tree" href="/en/matcher/configuration/matcher-contexts-and-sources" horizontal>
  Configure the contexts and sources a schedule reconciles.
</Card>

<Card title="Generating Reports" icon="chart-pie" href="/en/matcher/daily-reconciliation/matcher-generating-reports" horizontal>
  Review the results produced by scheduled runs.
</Card>