Skip to main content
A schedule sends a message to an agent when you’re not around, either once at a time you pick or over and over on a cron. You’ll set up both, point one at a conversation that already exists, and read back what happened.

​
1. Schedule one message

Idempotency-Key is required. Send the same key twice and you get the same schedule back instead of a second one:
runAt is any RFC 3339 time in the future. Set it a couple of minutes out and you can watch this one go. spawn starts a fresh thread every time the schedule fires, which keeps unrelated runs out of one context window. Once a once schedule fires, it sets completedAt and flips enabled to false. Give it new once timing to bring it back.

​
2. Make it recurring

Five-field cron plus an IANA timezone, so it follows daylight saving where the person reading it lives:

​
3. Or keep it in one conversation

Point target at a thread the same agent already owns. Each fire is queued onto that thread, so the agent keeps its context from run to run:

​
4. Pause or delete

Pausing keeps the schedule and its history:
DELETE /v1/schedules/{scheduleId} removes it for good. Threads it already started stay where they are.

​
Check it worked

After the run time passes, read the schedule back:
lastStatus is fired, skipped, or failed. lastThreadId points at the thread the message landed in; open its events to see what the agent did. nextAt is when it runs again.

​
When it goes sideways

  • lastStatus: skipped. The previous scheduled turn was still running. Fires don’t stack up behind each other, so the late one is dropped.
  • disabledReason: thread_not_found. A thread target pointed at a thread that no longer exists, so Matrices switched the schedule off rather than guessing. A fire that fails outright switches it off the same way.
  • Nothing fires at all. Check the agent’s identity. Disabling one stops every schedule under it.

​
Where next

Wire up a team

Let one agent’s output wake another.

Schedules

Timing, targets, and what a fire freezes.