Retention API
Preview records selected by retention rules, then apply pruning.
Operations
| Operation | Method | Path |
|---|---|---|
retentionApply | POST | /api/v2/retention/apply |
retentionPlan | POST | /api/v2/retention/plan |
retentionApply
The same report as plan; with dry_run:false each eligible root is pruned in its own transaction under a root lock with eligibility re-checked, and a storage failure rolls that root back while the batch continues (action failed with error). Only the journal tables in pruned_tables are deleted; traverser rows, usage, run metadata, replays, emitter lineage, credentials, sessions and memory are retained, so idempotency keys stay spent and traversers.get keeps answering. Repeat with the same cutoff until scanned is 0, or page with next_after_seq. With mode sessions each eligible session's brief artifacts are deleted under the session row lock (rows_deleted.brief_artifacts); the session, its runs, memory and knowledge stay; page with cursor.
Request body
{
"cutoff": 0
}Responses
| Status | Body | Meaning |
|---|---|---|
200 | RetentionReport | Successful operation |
400 | ErrorResponse | Structured API error |
401 | ErrorResponse | Missing or invalid credentials |
403 | ErrorResponse | Role or ownership denied |
404 | ErrorResponse | Resource unavailable to this identity |
409 | ErrorResponse | Revision, idempotency, immutable version or lease conflict |
413 | ErrorResponse | Structured API error |
422 | ErrorResponse | Capability input/output schema violation |
429 | ErrorResponse | Capacity exceeded |
500 | ErrorResponse | Structured API error |
503 | ErrorResponse | Structured API error |
Example response 200
{
"after_seq": 0,
"cutoff": 0,
"dry_run": false,
"eligible": 0,
"evaluated_at": 0,
"exhausted": false,
"failed": 0,
"limit": 0,
"mode": "string",
"namespace": "string",
"next_after_seq": 0,
"next_cursor": "string",
"operation": "string",
"pruned": 0,
"pruned_tables": [
"string"
],
"retained_tables": [
"string"
],
"roots": [
{
"action": "string",
"descendants": 0,
"error": {
"code": "string",
"message": "string"
},
"finished_at": 0,
"principal": "string",
"reason": "string",
"root_id": "string",
"rows": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"seq": 0,
"status": "queued"
}
],
"rows_deleted": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"rows_planned": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"scanned": 0,
"sessions": [
{
"action": "string",
"artifacts": 0,
"bytes": 0,
"error": {
"code": "string",
"message": "string"
},
"principal": "string",
"reason": "string",
"rows": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"session_id": "string",
"updated_at": 0
}
],
"skip_reasons": {
"key": 0
},
"skipped": 0
}retentionPlan
Read-only report of the next batch (limit, default 100) of finished root executions in the caller's namespace whose whole tree finished strictly before cutoff, with the journal rows that would be pruned and the reason for every skip (active lease, unfinished descendant, recent activity, pending approval, active session). With mode sessions the batch is instead the sessions with brief artifacts whose last activity is strictly before cutoff (skips: session_active, unfinished_traverser, recent_activity), paged with cursor / next_cursor and reported under sessions. dry_run:false is rejected here; a body namespace field is rejected (400 invalid_retention_request). Non-admins get 403 before any read.
Request body
{
"cutoff": 0
}Responses
| Status | Body | Meaning |
|---|---|---|
200 | RetentionReport | Successful operation |
400 | ErrorResponse | Structured API error |
401 | ErrorResponse | Missing or invalid credentials |
403 | ErrorResponse | Role or ownership denied |
404 | ErrorResponse | Resource unavailable to this identity |
409 | ErrorResponse | Revision, idempotency, immutable version or lease conflict |
413 | ErrorResponse | Structured API error |
422 | ErrorResponse | Capability input/output schema violation |
429 | ErrorResponse | Capacity exceeded |
500 | ErrorResponse | Structured API error |
503 | ErrorResponse | Structured API error |
Example response 200
{
"after_seq": 0,
"cutoff": 0,
"dry_run": false,
"eligible": 0,
"evaluated_at": 0,
"exhausted": false,
"failed": 0,
"limit": 0,
"mode": "string",
"namespace": "string",
"next_after_seq": 0,
"next_cursor": "string",
"operation": "string",
"pruned": 0,
"pruned_tables": [
"string"
],
"retained_tables": [
"string"
],
"roots": [
{
"action": "string",
"descendants": 0,
"error": {
"code": "string",
"message": "string"
},
"finished_at": 0,
"principal": "string",
"reason": "string",
"root_id": "string",
"rows": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"seq": 0,
"status": "queued"
}
],
"rows_deleted": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"rows_planned": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"scanned": 0,
"sessions": [
{
"action": "string",
"artifacts": 0,
"bytes": 0,
"error": {
"code": "string",
"message": "string"
},
"principal": "string",
"reason": "string",
"rows": {
"approvals": 0,
"attempts": 0,
"brief_artifacts": 0,
"checkpoints": 0,
"events": 0,
"execution_artifacts": 0,
"node_logs": 0,
"signed_paths": 0,
"total": 0
},
"session_id": "string",
"updated_at": 0
}
],
"skip_reasons": {
"key": 0
},
"skipped": 0
}