Skip to main content
POST
Start an on-demand maintenance run

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

An on-demand maintenance run (§5.5).

scope
RunScopeIn · object
required

What an on-demand run covers: a catalog, schemas, or tables.

Combinations (namespace vs namespaces, bare table names) are checked by OnDemandService so the answer can name the offending field (422 issues).

operations
string[] | null

Operations to run: compaction, compact_deletes, rewrite_manifests, expire_snapshots, remove_orphans. Leave out to run every operation the policy enables.

mode
enum<string>
default:if_needed

if_needed skips the schedule but keeps the trigger conditions, so healthy tables are reported as skipped:healthy. force runs the selected operations regardless.

Available options:
if_needed,
force
dry_run
boolean
default:false

Run orphan removal as a dry run. The other operations have no dry-run mode; use the preview to see what would run.

overrides
Overrides · object | null

Policy fields for this run only. Never saved; locks and floors still apply. null is the same as {}.

overrides_yaml
string | null

The same overrides as YAML (the portal sends this). Not with overrides.

Maximum string length: 100000
priority
enum<string> | null

Overrides the policy's priority for this run.

Available options:
low,
normal,
high
ignore_window
boolean
default:false

Run outside the maintenance window.

Response

Successful Response

A maintenance run. summary has Task 21's shape: catalogs{name: {...}}, top_failures, worst_health.

id
string<uuid>
required
trigger
string
required
status
string
required
started_at
string
required
dag_run_id
string | null
requested_by
string | null
finished_at
string | null
tables_scanned
integer
default:0
tables_selected
integer
default:0
batches
integer
default:0
request
Request · object | null
summary
Summary · object