Cron Jobs
Schedule recurring jobs that run inside SapixDB — no external scheduler required.
What you'll learn
- ✓POST /v1/agents/:id/crons — name, schedule (5-field cron), action
- ✓action types: write to an agent, call a webhook
- ✓GET /v1/agents/:id/crons — list crons
- ✓DELETE /v1/agents/:id/crons/:name — remove
- ✓Standard cron expressions: * * * * * (every minute) to 0 0 1 * * (monthly)
Create a cron that writes a heartbeat record every minute. Wait 3 minutes. Verify 3 records were written.
What you'll learn
Schedule recurring SaQL queries that run automatically and write their results to an output agent.
How crons work
A SapixDB cron is a query-based scheduled task:
1. On every interval, it runs a SaQL query_config against a source agent
2. It writes the results to a designated output_agent_id
3. Each run is logged in _cron_runs for auditability
Crons are defined globally at /v1/crons — not per-agent.
Create a cron
curl -s -X POST http://localhost:7475/v1/crons \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{
"name": "hourly-paid-orders",
"description": "Snapshot paid orders every hour",
"interval_secs": 3600,
"query_config": {"type": "scan", "filter": {"field": "status", "op": "eq", "value": "paid"}, "limit": 1000},
"output_agent_id": "order-snapshots",
"use_interval_window": true,
"enabled": true
}' | python3 -m json.tooluse_interval_window: true restricts the query to records written in the last interval_secs window — useful for accumulating periodic snapshots without duplicates.
List crons
curl -s http://localhost:7475/v1/crons \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolFire a cron immediately
curl -s -X POST http://localhost:7475/v1/crons/hourly-paid-orders/trigger \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolView run history
curl -s http://localhost:7475/v1/crons/hourly-paid-orders/runs \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolEnable / disable
`bash
curl -s -X POST http://localhost:7475/v1/crons/hourly-paid-orders/disable \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"
curl -s -X POST http://localhost:7475/v1/crons/hourly-paid-orders/enable \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"
`
Delete a cron
curl -s -X DELETE http://localhost:7475/v1/crons/hourly-paid-orders \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"Challenge
Create a cron with interval_secs: 60 that queries all records from a events agent and writes results to a event-snapshots agent. Trigger it immediately with /trigger. Check the run log — confirm the run completed and records were written.
---