Schedules

Create a schedule

const schedule = await client.agents.schedules.create({
  name: "standup video",
  cron: "30 9 * * 1-5", // 9:30, Monday to Friday
  timezone: "Asia/Kolkata",
  session: {
    agent: { model: "anthropic/claude-sonnet-5.5" },
    environment: { type: "repos", repos: ["acme/demo"] },
    input:
      "Make a 30-second video for today's standup that sums up the commits of the last day. " +
      "Save it as out/standup.mp4.",
    limits: { max_cost_usd: 2 },
  },
  outputs: ["out/standup.mp4"],
  webhook: {
    url: "https://example.com/hooks/latentstack",
    events: ["run.completed", "run.failed", "session.failed", "schedule.skipped"],
  },
})

console.log(schedule.id, "next run:", schedule.next_run_at)
console.log("webhook secret:", schedule.webhook?.secret) // shown only now: give it to your receiver

Each weekday at 9:30 in India, a session clones acme/demo, makes the video and stops. The video is kept as an output, and the webhook's run.completed carries a link to download it.

• The session settings are checked when you save the schedule, as a create would check them: the model on your tier, the permission rules, and GitHub access to the repositories. A mistake fails now, not at 9:30.
• The answer is the schedule, with next_run_at, the next time it will run, in UTC.
• A schedule is yours alone, in the organization you made it in, like a session.

Each run

• At each time, LatentStack creates a session from session, as the person who made the schedule. Your API key, your membership of the organization and your tier are checked again first.
• The session's schedule_id says which schedule started it. So does the session block on its webhook events.
• It ends after its run: end_after_run is true unless session says false. Its patch is saved, its outputs copied and its webhook sent, then it stops. See End after the run.
• One time starts one session, even if LatentStack restarts while starting it.
• Its usage counts like that of any session you create, against your tier.

When a run is skipped

A time that doesn't start a session is recorded as skipped in the run ledger, and a schedule.skipped event is sent. The schedule stays on, and the next time runs as usual.

{
  "id": "evt_8c27d1e04b9a6f3e5d2c1b0a",
  "object": "event",
  "type": "schedule.skipped",
  "api_version": "v1",
  "created_at": "2026-10-15T04:00:04.212000+00:00",
  "sequence": null,
  "session": null,
  "data": {
    "schedule_id": "sch_1a2b3c4d5e6f7a8b9c0d1e2f",
    "due_at": "2026-10-15T04:00:00+00:00",
    "trigger": "clock",
    "reason": "previous_running",
    "message": "The previous run (ags_4843742656c9cbc90685c6d2) was still going."
  }
}

Concurrency

A run is still going while its session is starting, running or waiting for an approval. A session that is idle, paused or stopped doesn't hold the next run back.

The run ledger

Each run gets one row, and so does each skipped time. Rows are newest first.

const { data } = await client.agents.schedules.runs(schedule.id, { limit: 10 })
for (const run of data) console.log(run.due_at, run.outcome, run.reason ?? run.session_id, run.cost_usd)

The schedule's own last_run_at, last_session_id and last_outcome sum up the latest run.

Run now

const run = await client.agents.schedules.run(schedule.id)
console.log(run.session_id)

• Starts a session right away, outside the timetable. The next booked time doesn't change.
• The answer is the ledger row, with trigger: "manual" and the new session_id.
• With concurrency: "skip", it fails with conflict while the last run is still going.
• When a session can't be started right now (no capacity, or your organization at its session limit), it fails with runner_unavailable and the message says why. Try again shortly.
• Any other reason a run would be skipped is returned as the error, such as key_revoked.

Pause, change and delete

const schedules = client.agents.schedules

await schedules.update(schedule.id, { enabled: false }) // pause
await schedules.update(schedule.id, { enabled: true, cron: "0 10 * * 1-5" }) // resume, at 10:00 from now on
await schedules.delete(schedule.id)

• Pause with enabled: false. next_run_at becomes null. Turned on again, the next time counts from now: times that passed while it was paused don't run.
• Change any field; the others keep their values. A new cron or timezone books the next time from now. A new session replaces the settings and their files, and is checked again.
• A new webhook replaces the old one, whose waiting deliveries are marked failed. webhook: null (webhook=None in Python) removes it.
• Delete stops all further runs. Sessions it already started keep going, and its webhook stays for 7 days so they can still report.

Over HTTP

On POST, session.files is an object of path to base64 content, as on session create. Lists hold 20 items by default and up to 100; pass next_after as after for the next page.