Manage Taskstream history and retention
This reference explains how Workspace limits, retains, and protects Taskstream execution evidence with a legal hold. Use it when you need to inspect job history, preserve evidence, or decide whether a job can be deleted safely.
Taskstream remains in restricted security operation. Use history and retention actions only through an approved trusted-operator access path. External mutating Taskstream routes remain closed in the standard operating mode.
Evidence stored by Workspace
New public job logs contain a stable outcome class and, when available, the related occurrence and attempt IDs. Workspace limits result data to 64 KiB. Public history does not expose free-form infrastructure errors, credentials, SQL details, file paths, or DNS, TLS, and runtime failures.
Workspace marks truncated results and error sources separately. Older logs without a verified sanitization version remain hidden from the new public history contract. Workspace does not invent that evidence through a backfill.
Retention periods
| Evidence | Fixed V1 period |
|---|---|
| Job logs | 30 days after the log entry finishes |
| Terminal attempts | 365 days after completion |
| Terminal occurrences | 365 days after completion |
| Unreferenced authorization evidence | 365 days after revocation, expiry, or creation |
| Job definitions and technical controls | No automatic deletion |
A tenant-bound maintenance job removes expired, unprotected evidence in small batches. Archiving does not shorten a retention period. Use archiving to remove completed jobs from the active list without deleting their definition.
Read history
GET /api/v1/jobs/{jobId}/logs supports an opaque keyset cursor. Use cursor for new integrations. The default limit is 25 and the maximum is 200. Read the next cursor from meta.cursorPagination.nextCursor. A cursor never changes the tenant or job binding.
Existing clients can continue to use page and count, or offset and limit. This compatibility path also returns no more than 200 entries per request.
Place and release a legal hold
A legal hold protects the job definition, technical controls, logs, occurrences, attempts, and referenced authorization evidence. Use an identity with the dedicated taskstream:jobs:retention permission.
| Action | Endpoint | Required field |
|---|---|---|
| Place a hold | POST /api/v1/jobs/{jobId}/retention-hold | reason |
| Release a hold | POST /api/v1/jobs/{jobId}/retention-release | reason |
The normalized reason must be between 1 and 512 bytes. Provide a clear business reason, but never include passwords, tokens, or other credential values. Workspace records the actor, timestamp, and audit correlation. A release adds separate release evidence and does not overwrite the original hold reason.
Only one hold can be active for a job. Releasing a job without an active hold, or placing a second hold concurrently, returns a stable conflict.
Decide whether deletion is safe
Workspace blocks a log reset while a hold is active. Job deletion is also blocked while an occurrence is non-terminal, an attempt is active, or authorization evidence is still referenced.
Before deleting a job:
- Archive the job if you only need to remove it from the active list.
- Check whether a legal hold is active.
- Check for running or waiting executions.
- Release a hold only with business approval and a documented reason.
- Delete the job only after Workspace no longer reports a retention block.
TASKSTREAM_RETENTION_BLOCKED means evidence is still protected or referenced. TASKSTREAM_RETENTION_UNAVAILABLE means Workspace could not read the protection contract safely. Do not bypass either result with direct database changes.
Verify the result
Verification is complete when history returns only stable, bounded entries, the hold response identifies its actor and reason, and reset or delete returns a retention conflict while the hold is active. After an approved release, the closed hold remains available as audit evidence.
This feature does not replace a legal assessment of your retention and deletion obligations.