Skip to main content
Snaga
Try Snaga
Browse the documentation

Automation

Schedules

Have an agent start work on its own at set times — a morning digest, a weekly report — with a cron line and a time zone.

Plenty of work is the same job at the same time: the morning news digest, the Friday pipeline review, the end-of-month reconciliation. A schedule lets an agent start that work itself, so nobody has to remember to ask.

Each agent can have one schedule. When it fires, the platform starts an ordinary run of that agent with the input you stored, so everything you know about runs — streaming, approvals, costs — applies unchanged.

Set a schedule

curl -X PUT https://api.snaga.ai/api/v1/agents/<agent_id>/schedule \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 9 * * 1-5",
    "timezone": "Europe/Kyiv",
    "input": { "message": "Prepare the morning briefing" },
    "on_failure": "pause_schedule"
  }'
FieldMeaningDefault
cronWhen to fire, as a standard five-field cron line. Required.—
timezoneAn IANA time zone name, such as Europe/Kyiv.UTC
inputWhat each run receives, as in POST /api/v1/runs.{}
enabledSwitch the schedule on or off without deleting it.true
on_failureWhat to do when scheduled runs fail (below).retry_next
max_concurrent_scheduledHow many scheduled runs may be queued or running at once.1

A few rules keep schedules predictable:

  • Every five minutes at most. A cron line that would fire more often is refused with 422. An explicit list of minutes, such as 0,2,4, is the one exception.
  • A real time zone. An unknown name is refused, because the schedule would otherwise be saved and never fire.
  • A small, fixed delay. Each schedule fires between 0 and 9 minutes after its cron time; the offset is fixed per agent and spreads load. 0 9 * * * may fire at 09:02. next_fire_at always shows the actual moment.
  • No pile-ups. If firing would exceed max_concurrent_scheduled, that fire is skipped and the schedule waits for its next time.

PUT replaces the whole schedule: any field you leave out goes back to its default. Send the full configuration each time you change it.

When scheduled runs fail

on_failure decides what happens when a scheduled run fails:

ValueBehaviour
retry_nextKeep firing on schedule.
notifyKeep firing on schedule.
pause_scheduleAfter three failures in a row, pause the schedule.

The schedule counts consecutive_failures; a successful run sets it back to zero. To restart a paused schedule, PUT it again with enabled: true.

Check and remove schedules

curl https://api.snaga.ai/api/v1/agents/<agent_id>/schedule \
  -H "Authorization: Bearer $SNAGA_API_KEY"

The answer shows the configuration together with status (active, paused or error), next_fire_at, last_fired_at and consecutive_failures. An agent with no schedule answers 200 with null. On a disabled schedule, next_fire_at keeps its last value and may lie in the past — read enabled first.

GET /api/v1/schedules lists every schedule in your company in one call, with the agent's name.

DELETE /api/v1/agents/{agentId}/schedule stops the schedule for good. Runs it already started are not affected. Deleting needs the permission to delete agents, not only to edit them.

Reflective schedules

With autonomous_mode: true, a fire does not send the stored input. Instead the agent is given your reflection_prompt — for example "review pending work and plan the next steps". Use it for agents that should look after an area rather than repeat one fixed task.

Related

  • To run a multi-step plan with several agents on a timer, use a mission schedule.
  • To hear when a scheduled run finishes, subscribe to run.completed and run.failed with a webhook.
  • Every field is in the API reference.