curl --request POST \
--url https://api.example.com/api/maintenance/runs/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"scope": {
"catalog": "<string>",
"namespace": "<string>",
"namespaces": [
"<string>"
],
"tables": [
"<string>"
]
},
"operations": [
"<string>"
],
"mode": "if_needed",
"dry_run": false,
"overrides": {},
"overrides_yaml": "<string>",
"ignore_window": false
}
'import requests
url = "https://api.example.com/api/maintenance/runs/preview"
payload = {
"scope": {
"catalog": "<string>",
"namespace": "<string>",
"namespaces": ["<string>"],
"tables": ["<string>"]
},
"operations": ["<string>"],
"mode": "if_needed",
"dry_run": False,
"overrides": {},
"overrides_yaml": "<string>",
"ignore_window": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
scope: {
catalog: '<string>',
namespace: '<string>',
namespaces: ['<string>'],
tables: ['<string>']
},
operations: ['<string>'],
mode: 'if_needed',
dry_run: false,
overrides: {},
overrides_yaml: '<string>',
ignore_window: false
})
};
fetch('https://api.example.com/api/maintenance/runs/preview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/maintenance/runs/preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'scope' => [
'catalog' => '<string>',
'namespace' => '<string>',
'namespaces' => [
'<string>'
],
'tables' => [
'<string>'
]
],
'operations' => [
'<string>'
],
'mode' => 'if_needed',
'dry_run' => false,
'overrides' => [
],
'overrides_yaml' => '<string>',
'ignore_window' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/maintenance/runs/preview"
payload := strings.NewReader("{\n \"scope\": {\n \"catalog\": \"<string>\",\n \"namespace\": \"<string>\",\n \"namespaces\": [\n \"<string>\"\n ],\n \"tables\": [\n \"<string>\"\n ]\n },\n \"operations\": [\n \"<string>\"\n ],\n \"mode\": \"if_needed\",\n \"dry_run\": false,\n \"overrides\": {},\n \"overrides_yaml\": \"<string>\",\n \"ignore_window\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/maintenance/runs/preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"scope\": {\n \"catalog\": \"<string>\",\n \"namespace\": \"<string>\",\n \"namespaces\": [\n \"<string>\"\n ],\n \"tables\": [\n \"<string>\"\n ]\n },\n \"operations\": [\n \"<string>\"\n ],\n \"mode\": \"if_needed\",\n \"dry_run\": false,\n \"overrides\": {},\n \"overrides_yaml\": \"<string>\",\n \"ignore_window\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/maintenance/runs/preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"scope\": {\n \"catalog\": \"<string>\",\n \"namespace\": \"<string>\",\n \"namespaces\": [\n \"<string>\"\n ],\n \"tables\": [\n \"<string>\"\n ]\n },\n \"operations\": [\n \"<string>\"\n ],\n \"mode\": \"if_needed\",\n \"dry_run\": false,\n \"overrides\": {},\n \"overrides_yaml\": \"<string>\",\n \"ignore_window\": false\n}"
response = http.request(request)
puts response.read_body{
"tables": [
{
"registration_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"table": "<string>",
"role": "<string>",
"policy_version": "<string>",
"operations": [
{
"operation": "<string>",
"action": "run",
"status": "<string>",
"reason": "<string>",
"dry_run": false,
"triggers": [
"<string>"
]
}
],
"health": 123,
"error_kind": "<string>",
"est_bytes": 0,
"score": 0
}
],
"tables_in_scope": 123,
"tables_to_run": 123,
"operations_to_run": {},
"warnings": [
"<string>"
]
}What an on-demand run would do, without running it
curl --request POST \
--url https://api.example.com/api/maintenance/runs/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"scope": {
"catalog": "<string>",
"namespace": "<string>",
"namespaces": [
"<string>"
],
"tables": [
"<string>"
]
},
"operations": [
"<string>"
],
"mode": "if_needed",
"dry_run": false,
"overrides": {},
"overrides_yaml": "<string>",
"ignore_window": false
}
'import requests
url = "https://api.example.com/api/maintenance/runs/preview"
payload = {
"scope": {
"catalog": "<string>",
"namespace": "<string>",
"namespaces": ["<string>"],
"tables": ["<string>"]
},
"operations": ["<string>"],
"mode": "if_needed",
"dry_run": False,
"overrides": {},
"overrides_yaml": "<string>",
"ignore_window": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
scope: {
catalog: '<string>',
namespace: '<string>',
namespaces: ['<string>'],
tables: ['<string>']
},
operations: ['<string>'],
mode: 'if_needed',
dry_run: false,
overrides: {},
overrides_yaml: '<string>',
ignore_window: false
})
};
fetch('https://api.example.com/api/maintenance/runs/preview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/maintenance/runs/preview",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'scope' => [
'catalog' => '<string>',
'namespace' => '<string>',
'namespaces' => [
'<string>'
],
'tables' => [
'<string>'
]
],
'operations' => [
'<string>'
],
'mode' => 'if_needed',
'dry_run' => false,
'overrides' => [
],
'overrides_yaml' => '<string>',
'ignore_window' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/maintenance/runs/preview"
payload := strings.NewReader("{\n \"scope\": {\n \"catalog\": \"<string>\",\n \"namespace\": \"<string>\",\n \"namespaces\": [\n \"<string>\"\n ],\n \"tables\": [\n \"<string>\"\n ]\n },\n \"operations\": [\n \"<string>\"\n ],\n \"mode\": \"if_needed\",\n \"dry_run\": false,\n \"overrides\": {},\n \"overrides_yaml\": \"<string>\",\n \"ignore_window\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/maintenance/runs/preview")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"scope\": {\n \"catalog\": \"<string>\",\n \"namespace\": \"<string>\",\n \"namespaces\": [\n \"<string>\"\n ],\n \"tables\": [\n \"<string>\"\n ]\n },\n \"operations\": [\n \"<string>\"\n ],\n \"mode\": \"if_needed\",\n \"dry_run\": false,\n \"overrides\": {},\n \"overrides_yaml\": \"<string>\",\n \"ignore_window\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/maintenance/runs/preview")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"scope\": {\n \"catalog\": \"<string>\",\n \"namespace\": \"<string>\",\n \"namespaces\": [\n \"<string>\"\n ],\n \"tables\": [\n \"<string>\"\n ]\n },\n \"operations\": [\n \"<string>\"\n ],\n \"mode\": \"if_needed\",\n \"dry_run\": false,\n \"overrides\": {},\n \"overrides_yaml\": \"<string>\",\n \"ignore_window\": false\n}"
response = http.request(request)
puts response.read_body{
"tables": [
{
"registration_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"table": "<string>",
"role": "<string>",
"policy_version": "<string>",
"operations": [
{
"operation": "<string>",
"action": "run",
"status": "<string>",
"reason": "<string>",
"dry_run": false,
"triggers": [
"<string>"
]
}
],
"health": 123,
"error_kind": "<string>",
"est_bytes": 0,
"score": 0
}
],
"tables_in_scope": 123,
"tables_to_run": 123,
"operations_to_run": {},
"warnings": [
"<string>"
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Body
An on-demand maintenance run (§5.5).
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).
Show child attributes
Show child attributes
Operations to run: compaction, compact_deletes, rewrite_manifests, expire_snapshots, remove_orphans. Leave out to run every operation the policy enables.
if_needed skips the schedule but keeps the trigger conditions, so healthy tables are reported as skipped:healthy. force runs the selected operations regardless.
if_needed, force Run orphan removal as a dry run. The other operations have no dry-run mode; use the preview to see what would run.
Policy fields for this run only. Never saved; locks and floors still apply. null is the same as {}.
The same overrides as YAML (the portal sends this). Not with overrides.
100000Overrides the policy's priority for this run.
low, normal, high Run outside the maintenance window.
Was this page helpful?

