---
title: Schedules and workflows over HTTP
description: List venom serve's scheduled background agents, start one now, read its runs and their output files, and list a workspace's workflow scripts.
section: server-api
order: 60
audience: [builder, operator, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/schedules.ts, docs/schedules.md, docs/workflows.md]
features: [server-api.schedules, server-api.workflows]
---

`venom serve` runs the jobs under `schedules:` in venom.yaml on their cron while it serves. These routes let an app show the jobs, start one on demand and read what each run did. How to write a job (cron, prompt, budget, roles, browser tasks) is configuration; this page covers the HTTP side.

## A job, end to end {#example}

```yaml
# ~/.venom/config.yaml
schedules:
  deps:
    cron: "0 3 * * 1-5"
    prompt: Update patch-level npm dependencies, run the tests, commit if they pass
    cwd: ~/work/api        # inside a --root
    mode: auto
    max_usd: 0.5
```

```bash
venom serve --root ~/work &
curl -s $S/v1/schedules -H "Authorization: Bearer $TOKEN"
curl -s -X POST $S/v1/schedules/deps/run -H "Authorization: Bearer $TOKEN"
curl -s "$S/v1/schedules/runs?schedule=deps&limit=5" -H "Authorization: Bearer $TOKEN"
```

```python
run = client.run_schedule("deps")
for r in client.schedule_runs(schedule="deps", limit=5):
    print(r["status"], r["costUsd"], r["summary"])
```

```ts
const run = await client.runSchedule("deps");
const runs = await client.listScheduleRuns({ schedule: "deps", limit: 5 });
```

## How a run behaves {#runs}

Each run is a session like a client's: inside a root, counted against `--max-sessions`, saved with `persist`. By default it works in a new git worktree of `cwd`, removed afterwards when nothing changed and kept when something did. Nobody is there to answer, so every approval request is denied at once and every `ask_user` question is declined. A run stops when its model calls reach the job's `max_usd` (status `budget`). A `ScheduleDone` hook event fires when it ends. The server checks every 30 seconds and catches up at most one missed run per job after a restart.

## Operations {#operations}

| Operation | Route | What |
|---|---|---|
| `listSchedules` | `GET /v1/schedules` | `{schedules: [...]}`: each job with `nextRunAt` and `lastRun`. Empty when the server has no schedules. |
| `runSchedule` | `POST /v1/schedules/{name}/run` | Starts a job now. 202 with `{run}` as it started (`status: running`); its session shows in `GET /v1/sessions`. 404 `schedule_not_found`, 409 `schedule_running`. |
| `listScheduleRuns` | `GET /v1/schedules/runs?schedule=&limit=` | Runs, newest first. `schedule` narrows to one job; `limit` defaults to 50, at most 500. |
| `getScheduleRunOutput` | `GET /v1/schedules/runs/{runId}/output?file=` | One file a browser task's run produced, as an attachment. 404 `run_not_found`, `output_not_found`. |

**A job** (`ScheduleInfo`): `name`, `cron` (empty for a job started only by events), `on` (events that start a run: `intent_closed`, `session_created`, `session_timeout`, `tool_call` with `tools`), `queued`, `prompt`, `cwd`, `workspace`, `model`, `gear`, `role`, `browserTask`, `browser` (`headless`, `launch`, `extension`, `attach`), `params`, `allow`, `mode`, `maxUsd`, `enabled`, `running`, `nextRunAt` (in the past when a run was missed) and `lastRun`.

**A run** (`ScheduleRun`):

| Field | What |
|---|---|
| `id`, `schedule` | The run and its job |
| `trigger` | `cron`, `catch-up` (missed while the server was down), `manual`, or `event` (with `event` naming it) |
| `status` | `running`, `completed`, `error`, `aborted`, `budget` (stopped at `maxUsd`), `skipped` |
| `startedAt`, `endedAt`, `durationMs` | Timing |
| `costUsd` | Its model calls at list price (0 for local models) |
| `summary`, `error` | The final answer in one line (at most 300 characters), and the error if any |
| `piSessionId` | The saved session; resume it to continue ([Sessions](/docs/server-api/sessions.md#saved)) |
| `workspace`, `workspaceKept` | The worktree it ran in, and whether it was kept because the run changed something |
| `model` | The model it used |
| `browser` | For a browser task: `task`, `outcome` (`replayed` with no model call, `healed`, `failed`), `steps`, `done`, `failure`, `fallback`, `outputs`, `files` |
| `watch` | For a page watch's check that fired or failed: `name`, `url`, `fired`, `summary`, `actions`. Its `schedule` is `watch:<name>` |

A browser task's `files` are the names `getScheduleRunOutput` takes: `result.json`, `<name>.txt` for an extract step, `answer.md` when the model took over, `downloads/<file>`.

```bash
curl -s "$S/v1/schedules/runs/$RUN/output?file=result.json" -H "Authorization: Bearer $TOKEN" -o result.json
```

```python
data = client.schedule_run_output(run_id, "result.json")   # bytes
```

## Workflows {#workflows}

`GET /v1/workflows?cwd=<workspace>` (`listWorkflows`) lists the workflow scripts under the workspace's `.venom/workflows/`, as `venom workflow list` does: `{workflows: [{name, file}]}`. `cwd` is required and follows a session's `cwd` rules (403 `root_not_allowed`).

```python
for w in client.workflows("/home/me/work/app"):
    print(w["name"], w["file"])
```

The route only lists. To run one, prompt a session with `/workflow run <name>`; it goes through the session's permission mode, and its progress arrives as `workflow` events.

## Related pages

- [Sessions](/docs/server-api/sessions.md)
- [Events](/docs/server-api/events.md#harness)
- [Phone inbox](/docs/server-api/mobile-and-inbox.md): role and browser-task runs are filed in the inbox
