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

# Automations

> Schedule, manage, and inspect subject-scoped background agent runs.

Automations run an agent prompt on a schedule. Each automation belongs to one
agent and one stable `subjectId`, and every occurrence runs in a fresh session
with that subject's persistent workspace and memory.

All schedules use UTC. Herm accepts an ISO timestamp, a one-time duration such
as `30m`, a recurring interval such as `every 2h`, or a five-field cron
expression.

## Create an automation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST \
  "https://api.herm.run/v1/agents/agent_123/users/customer_123/automations" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PRISM_API_KEY" \
  -d '{
    "name": "Weekly account summary",
    "prompt": "Review this account and write the weekly summary.",
    "schedule": "0 9 * * 1",
    "skills": ["account-review"],
    "enabled": true
  }'
```

| Field      | Type      | Required | Description                                                                     |
| ---------- | --------- | -------- | ------------------------------------------------------------------------------- |
| `name`     | string    | No       | Display name, up to 200 characters.                                             |
| `prompt`   | string    | Yes      | Prompt for each run, up to 5,000 characters.                                    |
| `schedule` | string    | Yes      | ISO timestamp, duration, recurring interval, or five-field UTC cron expression. |
| `skills`   | string\[] | No       | Configured skill names to make available, up to 64 entries.                     |
| `repeat`   | integer   | No       | Stop after this many completed occurrences.                                     |
| `enabled`  | boolean   | No       | Whether scheduled occurrences can run. Defaults to `true`.                      |

The response includes the normalized `schedule`, human-readable
`scheduleDisplay`, `nextRunAt`, current `state`, and run counters.

## List automations

List automations for one subject:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://api.herm.run/v1/agents/agent_123/users/customer_123/automations" \
  -H "x-api-key: $PRISM_API_KEY"
```

List automations across all subjects for an agent:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.herm.run/v1/agents/agent_123/automations" \
  -H "x-api-key: $PRISM_API_KEY"
```

## Read and update

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET   /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}
PATCH /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}
```

`PATCH` accepts any subset of the create fields. Set `repeat` to `null` to
remove a repeat limit.

## Pause, resume, and trigger

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/pause
POST /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/resume
POST /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/trigger
```

Manual trigger returns the new `sessionId` and does not change `nextRunAt`.
Pause prevents scheduled occurrences without deleting history; resume computes
the next eligible occurrence.

## Run history

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://api.herm.run/v1/agents/agent_123/users/customer_123/automations/automation_123/sessions?limit=20" \
  -H "x-api-key: $PRISM_API_KEY"
```

The response lists the fresh sessions created by scheduled and manual runs.
Follow each session through the normal [event stream](/api-reference/stream-events).

## Delete

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DELETE /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}
```

Deletion stops future runs while preserving historical sessions. Scheduled
work is recovered after transient gateway failures, so external side effects
should be idempotent.