---
title: "Submit a DuckLake maintenance job"
method: POST
path: "/v4/admin/lake/maintenance/{integration_id}"
tags: ["v4", "Admin"]
---

# Submit a DuckLake maintenance job

`POST /v4/admin/lake/maintenance/{integration_id}`

## Path parameters

- `integration_id` union, required
  - string, uuid
  - string

## Request body

- DuckLakeMaintenanceRequest
  - `steps` DuckLakeMaintenanceStepName[], nullable — Subset of maintenance steps to run. If omitted, all steps run. Steps are always executed in the canonical order regardless of input order.
  - `deleteThreshold` number, nullable — Delete ratio threshold for ducklake_rewrite_data_files (0.0–1.0). Files with a delete ratio above this value are rewritten. Default is 0.95 if omitted.
  - `expireSnapshotsOlderThan` string, nullable — Interval for ducklake_expire_snapshots older_than parameter (e.g. '1 week', '1 month'). Snapshots older than this are expired. If omitted, the integration's history_days setting is used.
  - `cleanupAll` boolean — When true, ducklake_cleanup_old_files and ducklake_delete_orphaned_files clean up all files regardless of age. When false, DuckLake's default age-based behaviour is used.
  - `cpu` string — CPU cores for the K8s job in Kubernetes format (e.g., '4', '15', '500m'). Defaults to 15 cores.
  - `memory` string — Memory for the K8s job in Kubernetes format (e.g., '96Gi', '192Gi'). Increase for catalogs with many files (150K+). Defaults to 96Gi.
  - `timeoutSeconds` integer — Pod timeout in seconds for the maintenance K8s job (60–604800). Defaults to 43200 (12 hours).
  - `thinKeepLast` integer — Always keep the N most recent snapshots (safety floor)
  - `thinKeepDailyForDays` integer — Keep 1 snapshot per day for the last D days
  - `vacuumFull` boolean — When true (default), the vacuum_catalog step runs VACUUM FULL ANALYZE, rewriting catalog metadata tables to reclaim bloat and refresh pg_stat row counts. When false, runs VACUUM ANALYZE only.
  - `mergeConcurrency` integer — Number of tables to merge in parallel. Higher values speed up catalogs with many tables but use more memory. Defaults to 4.
  - `runThreshold` 'any' | 'warning' | 'critical' — Minimum catalog health severity at which scheduled maintenance runs.

## Response `202`

Success

- SuccessResponseDuckLakeMaintenanceJobResponse
  - `success` true, required — Flag for it request was successful
  - `data` DuckLakeMaintenanceJobResponse, required
    - `jobId` string, required — K8s batch job name for polling
    - `maintenanceId` string, required — ID used to track steps in __definite.maintenance
    - `integrationId` union, required — DuckLake integration used
      - string, uuid
      - string
    - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'unknown', required — Status of an async DuckDB K8s job.
  - `meta` ResponseMeta
    - `requestId` string — Unique request identifier for tracing
    - `timestamp` string, date-time — Response timestamp (UTC)
    - `durationMs` integer, nullable — Request processing time in milliseconds

## Other responses

- `401` — Auth Invalid Token
- `403` — Forbidden Insufficient Permissions
- `404` — Resource Not Found
- `409` — Resource Conflict
- `422` — Validation Failed
- `426` — Business Quota Exceeded
- `500` — Internal Error

---

[API](https://skmtc.dev/definite/apis/defapi.md) · [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/definite/defapi/revisions/3943d8deb3be/schema)