Skip to content
Docs menu

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.

View .md

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.5
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"
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.json
data = client.schedule_run_output(run_id, "result.json")   # bytes

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).

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.