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

# Schedules

> Work that starts without you.

A schedule sends a message to an [agent](/model/agents) later, either once or
on a repeat. Check a queue every morning, prepare a weekly digest, follow up in
three days, that kind of thing.

Timing is either `once` with an RFC 3339 `runAt`, or `repeated` with a standard
five-field `cron` and an IANA `timezone`. After a one-time schedule fires it
flips `enabled` to `false` and sets `completedAt`; give it new `once` timing if
you want to reuse it.

The target decides where the message lands. `{ "mode": "spawn" }` starts a
fresh thread on each fire, which keeps unrelated runs from piling into one
context window. `{ "mode": "thread", "threadId": "..." }` queues onto a thread
the same agent already owns.

Each fire uses the agent's configuration as it is at that moment: its profile,
roles, tools, and model. If the previous scheduled turn is still running, the
next fire is skipped rather than run on top of it. Creating a schedule requires
an `Idempotency-Key` header. The same key twice returns the original schedule;
the same key with different fields is rejected.

After each fire, `lastStatus` is `fired`, `skipped`, or `failed`, with
`lastThreadId` and `lastTurnId` pointing at the work. A schedule that can no
longer run is disabled with a `disabledReason` of `agent_not_found`,
`thread_not_found`, or `invalid_config`.

<Info>
  **Belongs to** one agent · **Timing** is `once` or `repeated` · **Target** is
  `spawn` or an existing thread · **Paused** with `enabled: false`
</Info>

## Rules

* Overlapping fires are skipped, never queued behind each other. See
  [Rules](/model/rules).
* Disabling an agent's identity stops its schedules firing.

## API

* `GET`/`POST /v1/agents/{agentId}/schedules`. `limit` maxes out at 100 here,
  not 200.
* `GET`/`PATCH`/`DELETE /v1/schedules/{scheduleId}`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.