Scheduled Tasks & Jobs API

Enterprise

Create and manage NetStacks Controller scheduled tasks (backups, deployments, health checks, scripts, AI agent tasks), run them on demand, and read job history.

Overview

Scheduled tasks are the API behind Config Automation → Scheduled Tasks. Each task has a type, a cron schedule, a time zone, and a parameters object that depends on the type. For the UI wizard, see Scheduled tasks.

The task endpoints need devices.access. They return errors as plain text rather than JSON (see Errors).

Endpoints

Method	Path	Purpose	Permission
`GET`	`/api/tasks/schedules`	List tasks: `{"tasks":[…],"total","limit","offset"}`	`devices.access`
`POST`	`/api/tasks/schedules`	Create a task	`devices.access`
`GET`	`/api/tasks/schedules/:task_id`	Get a task	`devices.access`
`PUT`	`/api/tasks/schedules/:task_id`	Update a task (only the fields you send)	`devices.access`
`DELETE`	`/api/tasks/schedules/:task_id`	Delete a task (`204`)	`devices.access`
`POST`	`/api/tasks/schedules/:task_id/run`	Run the task now (`202`)	`devices.access`
`POST`	`/api/tasks/schedules/:task_id/toggle`	Enable or disable. Body: `{"enabled": true}`	`devices.access`
`GET / POST`	`/api/tasks/agent-schedules`	List or create AI agent task schedules	`devices.access`
`GET / PUT / DELETE`	`/api/tasks/agent-schedules/:task_id`	Get, update, or delete an agent schedule	`devices.access`
`POST`	`/api/tasks/agent-schedules/:task_id/run \| toggle`	Run now, or enable/disable	`devices.access`
`POST`	`/api/tasks/executions/:id/cancel`	Cancel a running execution	`devices.access`
`GET`	`/api/admin/agent-tasks/history`	Run history. Query: `task_id`, `limit`, `offset`	`users.manage`
`GET`	`/api/config/jobs/upcoming`	Enabled tasks ordered by next run time	`devices.access`
`GET`	`/api/config/jobs`	Recent jobs: MOP runs, deployments, snapshots, task runs	`devices.access`
`GET`	`/api/activity`	Activity feed across features (filters below)	`devices.access`

Create a scheduled task

curl -s --cacert netstacks-ca.pem -X POST https://controller.example.com:3000/api/tasks/schedules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Config Backup",
    "task_type": "backup",
    "cron_expression": "0 2 * * *",
    "timezone": "America/Chicago",
    "parameters": { "device_filter": { "device_type": "cisco_ios" } }
  }'

Field	Type	Notes
`name`	string	Required.
`task_type`	string	Required. `backup`, `deployment`, `health_check`, `custom_script`, or `agent_task`.
`cron_expression`	string	Required. Five-field cron, for example `0 /6 * *`. Invalid expressions return `400`.
`parameters`	object	Required. Depends on the type (see below). Send `{}` if none.
`timezone`	string	IANA time zone, for example `Europe/London`. Default `UTC`.
`description`	string	Optional.
`enabled`	boolean	Default `true`.
`max_retries, retry_delay_seconds, timeout_seconds`	integer	Optional retry and timeout settings.

The response is 201 with the task, including the calculated next_run_at.

Parameters by task type

`task_type`	UI label	`parameters`
`backup`	Config Backup	`snapshot_name` (optional, defaults to the task name), `device_filter`: `{"site_id": "…", "device_type": "…"}`. Each run creates a config snapshot.
`deployment`	Deployment	Either `stack_instance_id` (deploy a saved instance), or `stack_id` + `target_devices` + `variable_values` (same shapes as a deployment).
`health_check`	Health Check	Target devices: `device_ids` (array of UUIDs), or `device_filter`: `{"site": "…", "device_type": "…"}`.
`custom_script`	Custom Script	`script`: commands, one per line (lines starting with `#` or `!` are skipped), plus target devices as for `health_check`.
`agent_task`	Agent Task	`prompt`: the instruction for the AI agent.

Run now, enable, disable

# Run immediately
curl -s --cacert netstacks-ca.pem -X POST \
  https://controller.example.com:3000/api/tasks/schedules/$TASK/run \
  -H "Authorization: Bearer $TOKEN"

# Disable
curl -s --cacert netstacks-ca.pem -X POST \
  https://controller.example.com:3000/api/tasks/schedules/$TASK/toggle \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"enabled": false}'

/run returns 202 with the new execution: id, task_id, state, triggered_by, started_at, completed_at, output, error_message, retry_count. Use the execution id with POST /api/tasks/executions/:id/cancel to stop it.

Agent task schedules

/api/tasks/agent-schedules is a simpler form for AI agent tasks, used by the Terminal's scheduled tasks panel. The body has name, prompt, cron_expression, and optional description, timezone, and enabled:

{
  "name": "Morning BGP check",
  "prompt": "Check BGP neighbor state on all edge routers and summarize anything not Established.",
  "cron_expression": "0 9 * * 1-5",
  "timezone": "UTC"
}

Note

Agent tasks run with the permissions of the user who created them. See AI agents.

Jobs and activity

GET /api/activity is the feed behind Activity → Job History. It combines MOP runs, deployments, snapshots, task runs, SSH sessions, AI agent runs, scripts, and more. Query parameters (all optional, lists are comma-separated):

Field	Type	Notes
`category`	string	`mop`, `deployment`, `snapshot`, `task`, `ssh`, `ai_agent`, `script`, `triage`, `conversation`
`status`	string	For example `running`, `completed`, `failed`
`severity`	string	`error`, `warning`, `info`
`user`	string	Username, exact match
`search`	string	Matches the event name and summary
`since / until`	ISO datetime	Time range
`limit / offset`	integer	Default 50, maximum 200

curl -s --cacert netstacks-ca.pem \
  "https://controller.example.com:3000/api/activity?category=deployment,snapshot&status=failed&since=2026-10-11T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

The response is {"events":[…],"total":n,"stats":{…}}. Each event has id, category, name, status, severity, user_name, summary, timestamps, duration_ms, and device counts where they apply.