job

The job domain has 11 actions. On the meta surface they are all reached through arcane_job; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
job.ack_run	Acknowledge remote run completion	write
job.cancel_run	Cancel pending job run	write
job.get_run	Get job run	read
job.list	List all background jobs	read
job.list_runs	List job runs	read
job.resolve_run	Resolve legacy job run	write
job.restart_worker	Restart continuous job worker	write
job.retry_run	Retry job run	write
job.run	Run a job now	write
job.schedules_get	Get job schedules	read
job.schedules_update	Update job schedules	write

Actions

job.ack_run

Acknowledge remote run completion

• Kind: write
• Required parameters: jobId, runId
• Meta tool: arcane_job with "action": "ack_run"
• Individual tool: arcane_job_ack_run
• Arcane route: POST /api/environments/{id}/jobs/{jobId}/runs/{runId}/ack
• Operation ID: ack-job-run
• Since: Arcane v2.11.0
• Usage: Marks a finished run’s remote delivery as settled (remoteSettled true) so retention can compact its history. It does not change the run’s status. The run must be terminal (succeeded, partial, skipped, failed or canceled). runId from job.run or job.list_runs.
• Related actions: job.get_run, job.list_runs, job.retry_run

job.cancel_run

Cancel pending job run

• Kind: write
• Required parameters: jobId, runId
• Meta tool: arcane_job with "action": "cancel_run"
• Individual tool: arcane_job_cancel_run
• Arcane route: POST /api/environments/{id}/jobs/{jobId}/runs/{runId}/cancel
• Operation ID: cancel-job-run
• Since: Arcane v2.11.0
• Usage: Cancels a run only while it is queued and never attempted or delivered (otherwise ‘only unstarted pending runs can be canceled’). It cannot stop a running job. runId from job.run or job.list_runs. In practice only a run queued behind a still-running run of the same job is catchable. The result is the run with status canceled.
• Related actions: job.list_runs, job.get_run, job.run

job.get_run

Get job run

• Kind: read
• Required parameters: jobId, runId
• Meta tool: arcane_job with "action": "get_run"
• Individual tool: arcane_job_get_run
• Arcane route: GET /api/environments/{id}/jobs/{jobId}/runs/{runId}
• Operation ID: get-job-run
• Since: Arcane v2.11.0
• Usage: Reads one run: status (queued, waiting, running, retrying, succeeded, partial, skipped, failed, canceled, or legacy needs_attention), attemptCount, attempts, outcome, activityId (for activity.get, set on manual and other user-visible runs), timestamps and remote delivery flags. runId comes from job.run or job.list_runs. Poll this after job.run until the status is terminal.
• Related actions: job.run, job.list_runs, job.retry_run, job.ack_run, activity.get

job.list

List all background jobs

Get status, schedule, and metadata for all background jobs

• Kind: read
• Required parameters: none
• Meta tool: arcane_job with "action": "list"
• Individual tool: arcane_job_list
• Arcane route: GET /api/environments/{id}/jobs
• Operation ID: list-jobs
• Usage: Start here: lists every background job of the environment with its id (the jobId of the other job actions), schedule, nextRun, enabled, canRunManually, isContinuous, prerequisites, currentRun and lastRun. For a remote environment the agent’s catalog is returned (isAgent true). Requires the jobs:manage permission.
• Related actions: job.run, job.list_runs, job.schedules_get, job.restart_worker

job.list_runs

List job runs

• Kind: read
• Required parameters: jobId
• Meta tool: arcane_job with "action": "list_runs"
• Individual tool: arcane_job_list_runs
• Arcane route: GET /api/environments/{id}/jobs/{jobId}/runs
• Operation ID: list-job-runs
• Since: Arcane v2.11.0
• Usage: Paginated run history of one job (jobId from job.list): page (default 1) and limit (default 20, max 100). The result has runs, total, page and limit. For a remote environment it merges the agent’s history with the manager’s delivery records. Use it to find a runId for job.get_run, job.retry_run or job.ack_run.
• Related actions: job.list, job.get_run, job.retry_run, job.ack_run

job.resolve_run

Resolve legacy job run

Deprecated compatibility endpoint for mixed-version upgrades. Removed in v3.

• Kind: write
• Required parameters: jobId, runId
• Meta tool: arcane_job with "action": "resolve_run"
• Individual tool: arcane_job_resolve_run
• Arcane route: POST /api/environments/{id}/jobs/{jobId}/runs/{runId}/resolve
• Operation ID: resolve-job-run
• Since: Arcane v2.11.0
• Usage: Deprecated (removed in Arcane v3): marks a needs_attention run as reviewed by setting it canceled with a resolution. Any other status is refused with ‘only runs needing attention can be resolved’. Arcane (v2.16.1 to v2.17.2) records such outcomes as failed, so only runs of agents older than v2.16 can still be resolved. Otherwise use job.retry_run or job.run. Leave resolvedBy empty: only the manager-to-agent transport may set it.
• Related actions: job.get_run, job.retry_run, job.ack_run

job.restart_worker

Restart continuous job worker

• Kind: write
• Required parameters: jobId
• Meta tool: arcane_job with "action": "restart_worker"
• Individual tool: arcane_job_restart_worker
• Arcane route: POST /api/environments/{id}/jobs/{jobId}/restart
• Operation ID: restart-job-worker
• Since: Arcane v2.11.0
• Usage: Restarts the worker of a continuous job (isContinuous true in job.list, e.g. image-polling). Other jobs fail with ‘watcher not found’. It does not queue a run: use job.run for scheduled jobs. Remote environments forward the request to the agent.
• Related actions: job.list, job.run

job.retry_run

Retry job run

• Kind: write
• Required parameters: jobId, runId
• Meta tool: arcane_job with "action": "retry_run"
• Individual tool: arcane_job_retry_run
• Arcane route: POST /api/environments/{id}/jobs/{jobId}/runs/{runId}/retry
• Operation ID: retry-job-run
• Since: Arcane v2.11.0
• Usage: Requeues an existing run under the same runId, keeping its target progress. Only failed, partial or needs_attention runs are eligible (others fail with ‘run is not eligible for retry’), and on the local environment the job must still be enabled with its prerequisites met. Remote work whose outcome is not yet confirmed is refused (‘remote outcome must be confirmed before retry’). Poll job.get_run afterwards: attemptCount grows. To start a fresh run use job.run instead.
• Related actions: job.list_runs, job.get_run, job.run

job.run

Run a job now

Manually trigger a background job to run immediately

• Kind: write
• Required parameters: jobId
• Meta tool: arcane_job with "action": "run"
• Individual tool: arcane_job_run
• Arcane route: POST /api/environments/{id}/jobs/{jobId}/run
• Operation ID: run-job
• Usage: Queues a run of jobId (from job.list, and the job must be enabled, have canRunManually true and its prerequisites met) and returns 202 with runId and status. The job runs in the background. runId is optional: Arcane assigns a UUID when it is omitted, and passing your own UUID (as runId or idempotencyKey, which must agree) makes a repeated call return the same run instead of queuing another. Poll job.get_run with jobId and the returned runId until status is succeeded, failed, partial, skipped or canceled.
• Related actions: job.list, job.get_run, job.list_runs, job.cancel_run

job.schedules_get

Get job schedules

Get configured cron schedules for background jobs

• Kind: read
• Required parameters: none
• Meta tool: arcane_job with "action": "schedules_get"
• Individual tool: arcane_job_schedules_get
• Arcane route: GET /api/environments/{id}/job-schedules
• Operation ID: get-job-schedules
• Usage: Returns the cron expressions of the configurable job intervals (environmentHealthInterval, eventCleanupInterval, pollingInterval, scheduledPruneInterval, autoUpdateInterval, vulnerabilityScanInterval and others). Read it before job.schedules_update. job.list shows each job’s effective schedule and nextRun.
• Related actions: job.schedules_update, job.list

job.schedules_update

Update job schedules

Update background job cron schedules and reschedule running jobs

• Kind: write
• Required parameters: none
• Meta tool: arcane_job with "action": "schedules_update"
• Individual tool: arcane_job_schedules_update
• Arcane route: PUT /api/environments/{id}/job-schedules
• Operation ID: update-job-schedules
• Usage: Changes only the interval fields you pass (omit the others). Each value is a six-field cron expression with seconds (e.g. ‘0 30 */6 * * *’) or a descriptor such as ‘@every 5m’, and an invalid one rejects the whole request. Affected jobs are rescheduled immediately and the full schedule config is returned. Refused when Arcane’s UI configuration is disabled.
• Related actions: job.schedules_get, job.list