Automations

Last updated: 2026-09-06

What is an Automation?

An automation is an agent or a pod set to run on a cadence rather than by hand. It carries what runs, the context documents each run is seeded with, an optional opening prompt, the cron expression and timezone, and the window it is allowed to fire in.

The API and the domain model call this an Automation. The dashboard calls the same thing a Schedule wherever you actually work with one (the task box’s Schedule chip, the When to run popover, the Save schedule button), even though its sidebar link is labelled Automations. /api/schedules/* is an alias over the automation handlers, not a second implementation: the underlying table and the background ticker still say automation.

An automation targets exactly one agent or one pod, pinned to the exact target generation it was configured against. If you delete that agent or pod and create a new one with the same name, the automation does not silently pick it up: it is disabled instead (see Lifecycle below). Running a pod fires through the pod’s lead member. The lead delegates to the rest of the pod exactly as it would if a person had started the run, so the pod’s normal collaboration applies to a scheduled run too.

Automations, agents, and sessions

An automation does not run in some separate scheduling layer: firing it creates an ordinary run, through the same path as starting a run by hand. The readiness gate, spend caps, the credit gate, the concurrency cap and usage metering all apply exactly as they do to a run you start yourself. A schedule is never a way around those gates. Each firing opens a session that says it came from the automation, so the run sits in your normal Sessions list beside anything you started by hand.

Lifecycle and states

An automation is one of three statuses:

Status	Meaning
`active`	Fires on its cron expression, within its window.
`stopped`	Fires nothing. You stopped it, it was just created from a template, its window closed, or two firings in a row failed.
`disabled`	Cannot be started until its target is replaced: the agent or pod it points at was deleted.

An automation created through the API starts active, on the schedule it was given. Configuring a cadence is treated as the decision to run on it, and stopping it again is one request away. The one exception is a template install, which creates its automations stopped, so a copied workspace does not start spending on a schedule its new owner has never seen.

Start
Stop / pause
Run now

POST /api/automations/{id}/start sets the status to active and recomputes the next run from the schedule starting now; there is no catch-up for time the automation was off, so a schedule stopped on Monday and started on Friday does not owe Monday’s run. Starting also clears the automation’s consecutive-failure count.

POST /api/automations/{id}/stop clears the next run outright rather than suspending a countdown. POST /api/automations/{id}/pause is the same handler under an older name, kept as an alias. Starting again recomputes the next slot from now.

POST /api/automations/{id}/run fires one slot immediately, through the same path a scheduled firing takes: same gates, same firing record. It works on a stopped automation, so you can check the target, the context, and the credentials before turning the schedule on. It does not touch the schedule or start the automation; a stopped automation is still stopped afterwards.

Creating an automation also enforces one limit: the opening prompt is capped at 8KB. A cron expression and timezone are validated on every write, so a schedule that could never fire is rejected with a 400 rather than sitting in the list looking healthy. A start date may not fall before today in the automation’s own timezone: automations run forward from when they are set up and never backfill.

Two failed firings in a row switch an active automation to stopped on its own, with a paused reason of failed_twice recorded. A skip does not count as a failure, and neither does a stop you chose; only a firing whose run actually errored counts. Starting the automation again clears the count.

If the automation’s target is deleted, the next firing that discovers this disables the automation (disabledReason of agent_deleted, pod_deleted, or no_agents_remaining, plus disabledAt). A disabled automation must be pointed at a working target before it can be started again.

Missed slots

Each conductor replica checks for due automations roughly every 30 seconds. A slot more than one whole period late (an hour late matters to an hourly automation; it does not to a nightly one) is not caught up on. It is recorded as an interrupted firing and the schedule rolls forward to its next future slot, so a schedule that was offline for a while runs once at its next real slot rather than backfilling everything it missed. If the previous firing’s run is still going when the next slot comes due, the new slot is skipped rather than queued, and recorded as skipped_overlap.

Memory between firings

Every automation has a small, hidden agent working behind it that reads what happened after each run and rewrites one short note for the run that follows.

The note is written by that hidden agent, not by a fixed template, so what is worth remembering can differ per automation and you can read, tune or correct it.
It writes a note even for a run that crashed, by reading the run’s own record (status, failure reason, last thing said) rather than depending on the worker run to report on itself.
The note is capped at 8KB, is seeded into the next firing’s run alongside the automation’s attached contexts, and is distinct from those contexts: a context is configuration you attached by hand, the memory note is something an agent wrote.

Read and correct the note through its own endpoint:

curl https://api.orcapods.ai/api/automations/{id}/memory

curl -X PUT https://api.orcapods.ai/api/automations/{id}/memory \
  -H 'Content-Type: application/json' \
  -d '{"body": "Corrected note text, or an empty string to clear it."}'

{
  "automationId": "auto-9f1c2b7e",
  "body": "Last run finished the outline and drafted section 1...",
  "updatedAt": "2026-09-05T21:03:11Z"
}

An automation whose agent has not written yet returns an empty body: that is a state, not an error. The dashboard’s Memory Bank page shows the note read-only, filed under the automation’s own name, but does not offer a way to edit it there; use this endpoint to read or correct it.

Firings and history

Every scheduled slot is recorded as a firing, whether or not it started a run. A slot that quietly does nothing would otherwise be indistinguishable from a schedule that is broken, so even a skipped slot is written down with its reason.

Status	Meaning
`ok`	The run started. Whether it ultimately succeeded is the run’s own status.
`error`	The run was refused or failed outright.
`skipped_credits`	Refused by the credit gate, a spend cap, or the published-agent cap.
`skipped_overlap`	The previous run was still going, or the run was refused by the concurrency cap.
`skipped_target_deleted`	The target was confirmed deleted; the automation was disabled instead of firing.
`interrupted`	The slot was too late to be worth running and was rolled forward instead.

A firing costs up to two runs: the worker run itself, and the memory agent’s short follow-up run. Both are joined onto the firing at read time, so duration, tokens, and billed cost stay available without a second copy that could drift.

curl "https://api.orcapods.ai/api/automations/firings?automation={id}&outcome=failed&limit=50"

outcome groups firings for a history view: ok, failed, or skipped. Omit automation to list firings across every automation.

API

There is no CLI or SDK surface for automations today; use the dashboard or the REST API directly.

Create

curl -X POST https://api.orcapods.ai/api/automations \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "nightly-digest",
    "targetKind": "agent",
    "targetName": "researcher",
    "prompt": "Summarize what changed today.",
    "contexts": ["style-guide"],
    "cronExpr": "0 8 * * *",
    "timezone": "Europe/London"
  }'

List, get, update, delete

Method	Path	Notes
`GET`	`/api/automations`	Paginated, newest first. `q` filters by name, target, schedule, status, prompt, or contexts. `includeDeleted=true` retains soft-deleted rows for history views, and ignores `q` when set.
`GET`	`/api/automations/{id}`	One automation.
`PUT`	`/api/automations/{id}`	The name cannot be changed. Editing an active automation recomputes its next run.
`DELETE`	`/api/automations/{id}`	Blocked (`409`) while a worker run, delegated run, session, or memory update is still active. A successful delete keeps the automation, its firings, sessions, and runs as read-only history.

Turning cadence into cron

curl -X POST https://api.orcapods.ai/api/schedules/parse \
  -H 'Content-Type: application/json' \
  -d '{"text": "every weekday at 9am", "timezone": "Europe/London"}'

{
  "cron": "0 9 * * 1-5",
  "timezone": "Europe/London",
  "humanized": "Every weekday at 09:00",
  "nextRunAt": "2026-09-08T08:00:00Z"
}

This is a small, literal grammar rather than a model call, so text outside the accepted shapes is refused with a 422 rather than approximated.

Pods

Target a pod instead of a single agent.

Workflow orchestration

DAG-based multi-agent runs, for work with parallel or ordered subtasks.

Conductor API reference

Full route reference for the conductor’s /api/* surface.

Get Started

Core Concepts

Guides

Runbooks

Automations

What is an Automation?

Automations, agents, and sessions

Lifecycle and states

Missed slots

Memory between firings

Firings and history

API

Create

List, get, update, delete

Turning cadence into cron

Pods

Workflow orchestration

Conductor API reference

​What is an Automation?

​Automations, agents, and sessions

​Lifecycle and states

​Missed slots

​Memory between firings

​Firings and history

​API

​Create

​List, get, update, delete

​Turning cadence into cron

​Related

Pods

Workflow orchestration

Conductor API reference

What is an Automation?

Automations, agents, and sessions

Lifecycle and states

Missed slots

Memory between firings

Firings and history

API

Create

List, get, update, delete

Turning cadence into cron

Related