Overview
A loop starts its first batch immediately. Every occurrence can consume credits. maxCredits limits each batch, not lifetime spending.
Loops require scheduling support and account access. Both SDKs expose the complete lifecycle.
typescript
const loop = await agent.loop('Check acme.example', {
frequency: 'weekly',
schedule_config: { hour: 9, minute: 0, day_of_week: 1 },
timezone: 'America/New_York',
}, {
name: 'Weekly checks',
maxCredits: 20,
idempotencyKey: 'weekly-checks-001',
});
console.log(loop.id);Hour and minute are interpreted in the IANA timezone, which defaults to UTC. Weekly day_of_week uses 0 for Monday; monthly day_of_month accepts 1–28.
Pause or stop
typescript
await agent.pauseLoop(loop.id);
await agent.resumeLoop(loop.id);
await agent.deleteLoop(loop.id, { cancelActive: true });Pausing stops future occurrences. Deleting stops future work, and cancelActive also cancels pending work in the latest batch. Already running rows may finish. getLoop(id) returns batch history; read each batch with the batch APIs.
Python loops
python
loop = agent.loop("Check acme.example", {
"frequency": "weekly",
"schedule_config": {"hour": 9, "minute": 0, "day_of_week": 0},
"timezone": "America/New_York",
}, name="Monday checks", max_credits=20, idempotency_key="monday-checks-001")
history = agent.get_loop(loop["id"])
first_results = agent.get_batch_results(loop["first_batch_id"])
agent.pause_loop(loop["id"])
agent.resume_loop(loop["id"])
agent.delete_loop(loop["id"], cancel_active=True)Update and run now
updateLoop / update_loop accepts name, frequency, schedule_config, and timezone; it does not replace frozen inputs. runLoopNow / run_loop_now creates an extra batch without shifting cadence and returns batch_id and run_number. Overlapping active work returns a conflict. getLoop / get_loop returns loop and runs, including skip reasons and history. Use each history batch ID with the batch result APIs.