> For AI agents: the documentation index is at https://docs.gethandup.dev/llms.txt. Append .md to any page URL (without the trailing slash) for Markdown, for example https://docs.gethandup.dev/cli.md.

# cleanup_start

`POST /v1/storage/cleanup`

Start a background cleanup of resolved requests (never pending ones or files they reference). It runs in small batches, so requests and decisions keep working. Local, and decide scope on paired devices.

## Request Body required

Media type: `application/json`

`object`

Which resolved requests a cleanup covers (`POST /v1/storage/cleanup` body,
`GET /v1/storage/estimate` query). Both limits apply together.

- **target** (required): `string`

  What a cleanup removes.

  Allowed values: `history` `files`

- **older_than_days**: `integer` format: int32, >= 0

  Only requests resolved at least this many days ago; 0 = every resolved request.

- **keep_newest**: `integer` format: int32, >= 0

  Keep the newest this many resolved requests (requests resolved in the
  same millisecond as the last one kept stay too); 0 = no count limit.

## Responses

### 202

Started; poll GET /v1/storage/cleanup/{id}

Media type: `application/json`

`object`

A background cleanup. The daemon runs one at a time in small batches, so
requests and decisions keep working while it runs.

- **id** (required): `string`
- **target** (required): `string`

  What a cleanup removes.

  Allowed values: `history` `files`

- **older_than_days** (required): `integer` format: int32, >= 0

  0 = every resolved request.

- **keep_newest**: `integer` format: int32, >= 0

  Newest resolved requests kept; 0 = no count limit.

- **state** (required): `string`

  Allowed values: `running` `done` `cancelled` `failed`

- **total** (required): `integer` format: int64, >= 0

  Items to process, counted at the start: requests (history) or files (files).

- **done** (required): `integer` format: int64, >= 0

  Items processed so far.

- **requests_deleted** (required): `integer` format: int64, >= 0
- **files_deleted** (required): `integer` format: int64, >= 0
- **bytes_freed** (required): `integer` format: int64, >= 0

  Bytes freed: removed files plus database pages released by deleted rows.

- **compacting** (required): `boolean`

  Returning freed database pages to the filesystem (incremental vacuum).

- **started_at** (required): `integer` format: int64, >= 0

  Unix milliseconds.

- **finished_at**: `integer | null` format: int64, >= 0
- **error**: `string | null`

  Set when `state` is `failed`.

### 403

Remote device without decide scope

### 409

A cleanup is already running; `job` is that cleanup