Scheduler API

Base path: /api/scheduler

All endpoints require authentication. See API Overview for auth details.

Jobs

List jobs

GET /api/scheduler/jobs

Query parameters:

Parameter	Type	Description
status	string	Filter by status: active, paused, completed, failed
limit	int	Max results (default: 50, max: 200)
offset	int	Pagination offset

Response:

{
  "jobs": [
    {
      "id": "job_abc123",
      "name": "Daily digest",
      "goal": "Summarize today's activity",
      "schedule": {"type": "cron", "expression": "0 8 * * 1-5", "timezone": "America/New_York"},
      "status": "active",
      "agent_id": "agent_123",
      "next_run_at": "2026-03-03T08:00:00-05:00",
      "last_run_at": "2026-03-02T08:00:00-05:00",
      "run_count": 42,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "count": 10
}

Create a job

POST /api/scheduler/jobs

{
  "name": "Price alert",
  "goal": "Check BTC price and alert if >5% change",
  "agent_id": "agent_123",
  "schedule": {
    "type": "every",
    "interval": 3600,
    "timezone": "UTC"
  },
  "delivery": {
    "channel": "slack:#alerts",
    "format": "markdown"
  },
  "condition": {
    "type": "expression",
    "expression": "price_change_pct > 0.05"
  },
  "retry": {
    "max_attempts": 3,
    "strategy": "exponential",
    "base_delay": 60
  }
}

Schedule types:

Type	Required fields	Example
cron	expression, timezone	{"type":"cron","expression":"0 9 * * 1-5"}
every	interval (seconds)	{"type":"every","interval":3600}
at	datetime	{"type":"at","datetime":"2026-04-01T09:00:00Z"}

Returns 201 with the created job object directly (.to_dict() format).

Get a job

GET /api/scheduler/jobs/{id}

Update a job

PUT /api/scheduler/jobs/{id}

Send only the fields to update:

{"name": "Updated name", "schedule": {"type": "cron", "expression": "0 10 * * *"}}

Delete a job

DELETE /api/scheduler/jobs/{id}

Pause a job

POST /api/scheduler/jobs/{id}/pause

Resume a job

POST /api/scheduler/jobs/{id}/resume

Trigger a job immediately

POST /api/scheduler/jobs/{id}/trigger

Runs the job now, regardless of its schedule. Returns the run_id.

Job runs

List runs for a job

GET /api/scheduler/jobs/{id}/runs

Query: status, limit, offset

Response includes run objects with id, status, started_at, completed_at, output, error.

Get a specific run

GET /api/scheduler/jobs/{id}/runs/{run_id}

Cancel a run

POST /api/scheduler/jobs/{id}/runs/{run_id}/cancel

Natural language parsing

POST /api/scheduler/parse-nl

Parse a natural language schedule description:

{"text": "every weekday at 9am Pacific"}

Response:

{
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "America/Los_Angeles"
  },
  "human_readable": "At 09:00 AM, Monday through Friday, Pacific Time",
  "confidence": 0.95,
  "parse_method": "regex"
}

If the regex parser can’t parse the expression, it falls back to LLM parsing ("parse_method": "llm").

Schedule validation

GET /api/scheduler/validate?type=cron&value=0+9+*+*+1-5&timezone=America%2FNew_York

Query parameters: type (cron/every/at), value (expression or interval), timezone.

Response:

{
  "valid": true,
  "next_runs": [
    "2026-03-03T09:00:00-05:00",
    "2026-03-04T09:00:00-05:00",
    "2026-03-05T09:00:00-05:00"
  ]
}

Statistics

GET /api/scheduler/stats

Returns aggregate statistics:

{
  "total_jobs": 12,
  "active_jobs": 10,
  "total_runs_today": 45,
  "success_rate": 0.97,
  "avg_duration_seconds": 38,
  "jobs_by_status": {"active": 10, "paused": 2}
}

Scheduler status

GET /api/scheduler/status

Returns engine status:

{
  "running": true,
  "tick_interval_seconds": 30,
  "next_tick_at": "2026-03-02T14:00:30Z",
  "jobs_checked_last_tick": 10
}

Job chains

Job chains are DAG-based pipelines where one job’s completion triggers the next.

List chains

GET /api/scheduler/chains

Create a chain

POST /api/scheduler/chains

{
  "name": "Data pipeline",
  "jobs": ["job_fetch", "job_transform", "job_store"],
  "edges": [
    {"from": "job_fetch", "to": "job_transform", "type": "on_success"},
    {"from": "job_transform", "to": "job_store", "type": "on_success"},
    {"from": "job_fetch", "to": "job_store", "type": "on_failure"}
  ]
}

Edge types: on_success, on_failure, on_complete (always).

Get / Delete a chain

GET    /api/scheduler/chains/{id}
DELETE /api/scheduler/chains/{id}

Smart scheduling

Get schedule suggestions

GET /api/scheduler/smart/suggestions

Returns suggested schedule times based on your activity patterns:

{
  "suggestions": [
    {"time": "08:55", "days": "Mon-Fri", "reason": "5 min before typical start"},
    {"time": "17:30", "days": "Mon-Fri", "reason": "end of typical work day"}
  ]
}

Get activity heatmap

GET /api/scheduler/smart/heatmap

Returns a 24×7 grid of activity levels for visualization.

Additional endpoints

The following endpoints also exist but are not documented in full here:

Method	Path	Description
GET	/api/scheduler/jobs/{id}/stats	Per-job statistics
GET	/api/scheduler/calendar-data	Calendar data for scheduling UI