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

# Scheduling Automated Agent Runs

> How to create, manage, and monitor scheduled agent runs using cron expressions, view run history per schedule, and manually trigger executions.

Agent Manager supports scheduling recurring or one-time agent runs without any external job orchestration. Scheduled runs execute as background jobs and produce the same `RunResponse` as manually triggered runs, so they work with all the same monitoring and audit tooling.

## Common use cases

* Daily report generation (summarize overnight activity, generate executive briefings)
* Periodic data analysis (run analytics agents on a nightly or weekly cadence)
* Automated monitoring alerts (poll data sources and notify on anomalies)
* Batch knowledge base updates (re-ingest and refresh vector content on a schedule)

## Creating a schedule

<Steps>
  <Step title="Define the schedule payload">
    Build a `ScheduleDTO` with the agent to run, the message to send it, and the recurrence expression:

    ```json theme={null}
    {
      "name": "Daily Sales Summary",
      "agentId": "finance_agent",
      "message": "Generate a summary of today's sales data",
      "cronExpression": "0 8 * * *",
      "enabled": true
    }
    ```
  </Step>

  <Step title="Submit the schedule">
    ```bash theme={null}
    curl -X POST http://your-host/api/v1/schedules \
      -H "Authorization: Bearer {token}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Daily Sales Summary",
        "agentId": "finance_agent",
        "message": "Generate a summary of today'\''s sales data",
        "cronExpression": "0 8 * * *",
        "enabled": true
      }'
    ```

    The API returns `201 Created` with the new schedule including its assigned ID.
  </Step>
</Steps>

## Cron expression reference

Schedules use standard five-field cron syntax:

```
┌───── minute (0-59)
│ ┌───── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌───── month (1-12)
│ │ │ │ ┌───── day of week (0-7, Sunday = 0 or 7)
│ │ │ │ │
* * * * *
```

| Expression     | Meaning                              |
| -------------- | ------------------------------------ |
| `0 8 * * *`    | Every day at 8:00 AM                 |
| `0 * * * *`    | Every hour on the hour               |
| `30 9 * * 1`   | Every Monday at 9:30 AM              |
| `0 0 1 * *`    | First day of every month at midnight |
| `*/15 * * * *` | Every 15 minutes                     |

## Managing schedules

**List all schedules** (paginated):

```bash theme={null}
GET /api/v1/schedules
```

**Get a specific schedule:**

```bash theme={null}
GET /api/v1/schedules/{id}
```

**Update a schedule** (change message, recurrence, or enabled state):

```bash theme={null}
curl -X PUT http://your-host/api/v1/schedules/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Sales Summary",
    "agentId": "finance_agent",
    "message": "Generate a summary of today'\''s sales data",
    "cronExpression": "0 9 * * *",
    "enabled": true
  }'
```

**Delete a schedule:**

```bash theme={null}
DELETE /api/v1/schedules/{id}
```

Returns `204 No Content` on success.

## Triggering a schedule manually

To execute a schedule immediately without waiting for its next cron time:

```bash theme={null}
curl -X POST http://your-host/api/v1/schedules/{id}/trigger \
  -H "Authorization: Bearer {token}"
```

```json theme={null}
{
  "message": "Schedule execution triggered."
}
```

Manual triggers enqueue the same background job as an automatic execution.

## Viewing run history

To see the execution history for a specific schedule:

```bash theme={null}
GET /api/v1/schedules/{id}/runs
```

Each entry in the list corresponds to one execution and includes its status, start time, and outcome. You can also monitor background jobs produced by scheduled runs via the Jobs dashboard.

<Note>
  Scheduled runs execute as background jobs. If a scheduled run fails, the job status will show `FAILED` and the failure reason will be captured in the run record. The schedule itself continues to execute on its defined cadence regardless of individual run outcomes.
</Note>

## Batch jobs

Agent Manager also supports spot batch jobs for one-off bulk operations. View all batch jobs:

```bash theme={null}
GET /api/v1/schedules/batches
```

Each batch job entry includes its status, progress percentage, estimated cost, and the compute configuration it ran on.

<Tip>
  For time-sensitive schedules, use the manual trigger endpoint during testing to verify the agent produces the expected output before relying on the cron schedule in production.
</Tip>