Operations
HTTP Endpoints
The management API for listing, inspecting and triggering jobs.
Mounting the router
get_cron_router() returns a standard APIRouter. Mount it wherever you like; every path below is relative to that prefix.
from fastapi_crons import get_cron_router
app.include_router(get_cron_router(), prefix="/api")These endpoints are unauthenticated
The router ships without auth, and one of its routes runs a job on demand. Guard it with a dependency — see Dashboard for an example — or keep it off public networks.
Routes
| Method | Path | Purpose |
|---|---|---|
| GET | / | List every registered job. |
| GET | /{job_name} | Details for one job. |
| GET | /{job_name}/status | Current status of one job. |
| POST | /{job_name}/run | Trigger a job immediately. |
| GET | /health | Liveness and readiness probe. |
| GET | /system/status | Scheduler-wide status. |
| GET | /dashboard | The web dashboard, if installed. |
Route order matters, and it is already handled
/health, /system/status and /dashboard are registered before /{job_name}, so they are matched first rather than being swallowed as job names.
Listing jobs
curl http://127.0.0.1:8000/api/Returns an array of job objects. A single job has the same shape:
{
"name": "backup_database",
"expr": "0 2 * * *",
"tags": ["backup", "critical"],
"last_run": "2026-07-27T02:00:00+00:00",
"next_run": "2026-07-28T02:00:00+00:00",
"hooks": {"before_run": 1, "after_run": 1, "on_error": 2},
"config": {"max_retries": 3, "retry_delay": 5.0, "timeout": 600}
}Triggering a job
Runs the job immediately, without waiting for its schedule. The run is marked as a manual trigger in the hook context.
curl -X POST http://127.0.0.1:8000/api/backup_database/runHealth
Suitable for a Kubernetes liveness or readiness probe.
curl http://127.0.0.1:8000/api/health{
"status": "healthy",
"version": "2.4.0",
"uptime": 3600.5,
"jobs_total": 4,
"jobs_running": 1
}healthy, degraded or unhealthy.The version field can be stale
It reads fastapi_crons.__version__, which the release automation does not update. Do not use it to assert which release is deployed.