---
title: Scheduled
description: Run a saved Agents automation on a recurring schedule, and how its runs differ from one-shot generation jobs.
---

A schedule is a saved Agents automation that runs on a cadence: instructions, a
model, a cron expression, and a spend cap. When it fires, Sume runs it as an
Agent in a fresh thread and returns a structured run receipt.

**A cadence is the whole point.** If you want to call Sume from your own backend
when *your* user does something, you want the [Format API](/formats) instead —
same run engine, same receipt, addressed per call and with your inputs. Reach
for a schedule when nothing triggers the work except the clock.

Schedules are authored in the Agents dashboard, or by asking the Agent in chat
to set one up for you. The Developer API can list them, read them, start runs,
and monitor runs — it cannot create or edit them.

The rest of Scheduled lives on three pages linked from here:
[Create a schedule](/agents/actions/create),
[Runs and results](/agents/actions/runs), and
[Advanced: run a schedule via API](/agents/actions/api-trigger).

> **Scheduled and the Actions API.** The product is called Scheduled. The HTTP
> API namespace is still `/v1/actions`, ids are `aut_…`, and objects come back
> as `object: "action"` — those names are stable and are not changing. Read
> "Action" in this page as the wire spelling of a schedule.

## Schedule vs. generation job

A schedule run is not a job. It does not appear in `/v1/jobs` and it does not
use the job lifecycle described in
[Jobs and results](/workflows/jobs-and-results).

| | Schedule run | Generation job |
|---|---|---|
| Started by | A cron schedule, or `POST /v1/actions/{action_id}/runs` | `POST /v1/{family}-1.0/...` |
| Unit of work | Saved instructions executed by an Agent in a new thread | One model invocation |
| Read back from | `/v1/action-runs/{run_id}` | `/v1/jobs/{id}` |
| Statuses | `queued`, `processing`, `completed`, `failed`, `canceled`, `skipped` | See [Jobs and results](/workflows/jobs-and-results) |
| Result shape | `output` projected onto an output schema, plus `artifacts` | Job `result` |
| Overlap policy | `on_active_run` (`skip` or `reject`) | None |

Use a generation job when you want one model invocation. Use a schedule when you
want saved instructions that an Agent carries out on a cadence, possibly across
several generations.

If the task itself changes on every call and there is nothing worth saving, you
want [Agent Completions](/agents/completions) instead — same agent, no saved
object, instruction supplied per request.

## Anatomy of a schedule

`GET /v1/actions` and `GET /v1/actions/{action_id}` return this shape.

```json
{
  "id": "aut_...",
  "object": "action",
  "title": "Weekly product teaser",
  "status": "active",
  "trigger_type": "api",
  "api_trigger_enabled": true,
  "cron": null,
  "model": "...",
  "output_schema": null,
  "primary_output_key": null,
  "generation_spend_cap_usd_micros": 1000000,
  "last_run_at": "2026-07-30T09:00:00.000Z",
  "created_at": "2026-07-20T12:00:00.000Z",
  "updated_at": "2026-07-30T09:00:00.000Z",
  "invoke_url": "https://api.sume.com/v1/actions/aut_.../runs"
}
```

| Field | Notes |
|---|---|
| `status` | `active` or `inactive`. An `inactive` schedule rejects API runs. |
| `trigger_type` | `cron` or `api`. Fixed at create time. |
| `api_trigger_enabled` | When `true`, `POST /v1/actions/{action_id}/runs` is allowed. A `cron` schedule can also enable it. |
| `cron` | `{ "expr", "timezone", "next_run_at" }`, or `null` for the API-only case. |
| `output_schema` | Default structured output binding (`{ "name", "strict" }`), or `null` for the built-in default. Bind one in the dashboard; see [Structured output](/formats/structured-output). |
| `generation_spend_cap_usd_micros` | Per-run generation cap in USD micros. `null` means the $1.00 default applies. |
| `invoke_url` | The schedule's own invoke endpoint. |

The `instructions` text is deliberately omitted from the public shape. Read and
edit instructions in the dashboard.

## Triggers

The trigger type is chosen at create time and is immutable afterwards:

- **Scheduled** (`cron`) — the default. Runs on a 5-field cron expression in an
  IANA timezone.
- **API call** (`api`) — an advanced option: no cadence, runs only when your
  service calls `POST /v1/actions/{action_id}/runs`. See
  [Advanced: run a schedule via API](/agents/actions/api-trigger).

A cron schedule can additionally set `api_trigger_enabled` to accept API runs on
top of its cadence. An API-only one never has a cadence.

## Where schedules live

Author and monitor them at `https://www.sume.com/agents/scheduled`. See
[Create a schedule](/agents/actions/create) for the dashboard flow.

## Limits

| Limit | Value |
|---|---|
| `input` properties | 64 |
| `input` size | 2097152 UTF-8 bytes (2 MiB) |
| Default generation spend cap | $1.00 (`1000000` USD micros) when unset |
| Per-run spend cap override | Clamped to `min(request, schedule cap)` — it can lower the cap, never raise it |
| `Idempotency-Key` length | 1–255 characters |
| `limit` on list endpoints | 1–100, default 50 |

## What schedules do not support yet

Be aware of these gaps before you design around them:

- **Signing secrets are not self-serve yet.** `communication.webhook_url` is
  accepted, validated, stored, and delivered on `api.dev.sume.com` and
  `api.sume.com`. The contract is documented at
  [Run webhooks](/agents/run-webhooks).
- **No events endpoint.** `events_url` on a run receipt is always `null` — run
  lifecycle events are not exposed over the API. Use `status_url` and
  `result_url`.
- **No pagination.** List responses always return `has_more: false` and
  `next_cursor: null`.
- **No MCP tool and no CLI command.** Schedules are not exposed over
  [MCP](/mcp) or the [CLI](/cli).
- **No write endpoints.** The Developer API cannot create, edit, or delete a
  schedule.

## Next

- [Create a schedule](/agents/actions/create)
- [Runs and results](/agents/actions/runs)
- [Safe automation](/agents/safe-automation)
- [Advanced: run a schedule via API](/agents/actions/api-trigger)
- [Run webhooks](/agents/run-webhooks)