Schedules and workflows over HTTP
List venom serve's scheduled background agents, start one now, read its runs and their output files, and list a workspace's workflow scripts.
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
# ~/.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.5venom 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"run = client.run_schedule("deps")
for r in client.schedule_runs(schedule="deps", limit=5):
print(r["status"], r["costUsd"], r["summary"])const run = await client.runSchedule("deps");
const runs = await client.listScheduleRuns({ schedule: "deps", limit: 5 });How a run behaves
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
| 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) |
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>.
curl -s "$S/v1/schedules/runs/$RUN/output?file=result.json" -H "Authorization: Bearer $TOKEN" -o result.jsondata = client.schedule_run_output(run_id, "result.json") # bytesWorkflows
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).
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
- Events
- Phone inbox: role and browser-task runs are filed in the inbox