---
title: "Clean Task"
method: POST
path: "/tasks/{task_id}/clean"
tags: ["task-retention"]
---

# Clean Task

`POST /tasks/{task_id}/clean`

Delete content-bearing rows for a stale task.

Refuses on active tasks, in-flight workflows, or unprocessed events
regardless of `force`. The `force=true` flag only bypasses the
idle-threshold check.

## Path parameters

- `task_id` string, required

## Request body

- CleanTaskRequest
  - `force` boolean — Skip the idle-threshold check. Active-workflow and unprocessed-events checks still apply. Admin use only.
  - `idle_days` integer — Idle threshold in days (ignored when force=true).

## Response `200`

Successful Response

- CleanTaskResponse
  - `task_id` string, required
  - `cleaned_at` string, date-time, required
  - `messages_deleted` integer, required
  - `task_states_deleted` integer, required
  - `events_deleted` integer, required

## Other responses

- `422` — Validation Error

## Changes

> 55 revisions in range; 4 could not be searched.

- **2026-05-29** `12a516f4d9ac` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/scaleapi/apis/agentex-api/changes/tasks/:task_id/clean/post.md)

---

[API](https://skmtc.dev/scaleapi/apis/agentex-api.md) · [All operations](https://skmtc.dev/scaleapi/apis/agentex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scaleapi/agentex-api/revisions/1e0aaafd5780/schema)