Routines
A recurring responsibility with instructions, a schedule, a model, limits, tools, and an optional webhook.
A routine is the unit of work. Everything else — runs, traces, webhooks — exists because a routine ran.
Anatomy
Prop
Type
Instructions
Instructions should describe the outcome, evidence expectations, boundaries, and escalation behaviour that remain stable from run to run. Use variables for values such as a repository, a reporting window, or a campaign.
Writing instructions covers this in depth — it is the highest-leverage page in the knowledge base.
Schedule
Schedules use five-field cron expressions and an IANA timezone. The scheduler calculates the next occurrence in that timezone, including daylight-saving transitions.
0 9 * * 1This example runs at 09:00 every Monday in the routine's timezone. A cron
expression that can never produce a future occurrence is rejected with
400 invalid_schedule.
Limits
Every routine sets a maximum step count and a timeout. The service rejects
out-of-range limits and stops bounded execution when a limit is reached:
step_limit when the model runs out of steps, timed_out when the run exceeds
its deadline.
Limits are a cost and blast-radius control, not a performance setting. Raising
maxSteps lets a routine do more work per run and spend more tokens doing it.
Tools
Tools reach a routine through a connection, and
are governed by a per-routine tool policy.
A tool policy always references a saved connection — creating a routine with
inline tool definitions returns 400 tool_policy_requires_connection.
Lifecycle
| Status | Meaning |
|---|---|
draft | Editable, and available for manual proof runs. |
active | Eligible for scheduled execution. |
paused | Retained with history, but not scheduled. |
archived | Hidden from normal lists. Cannot run. |
Activation requires a successful manual run of the current configuration.
Changing instructions, model, variables, schedule, limits, webhook delivery,
discovered tools, or tool permissions returns the routine to draft and
requires a new manual proof. Pausing does not delete history or invalidate an
otherwise current proof.
Archiving is how deletion works: DELETE /v1/routines/:routineId sets the
status to archived and keeps the run history intact.
Webhooks
Adding a webhook URL returns a signing secret once in the same response. Only the encrypted form is stored, so rotating means setting the URL again. See Receive run webhooks.