Purge trace content
DELETE/v1/projects/:project_id/traces/:trace_id/content
Deletes the trace's steps object from storage and clears its content columns (file_id, error), cascading to every descendant trace and to all of their generations. A descendant holds its own steps object covering the same run, so the cascade is what makes the erasure complete rather than merely partial.
The rows survive as auditable skeletons with content_redacted_at set — ids, timestamps, step counts, and the generations' usage-attribution fields are preserved, because the billing and audit ledger must outlive a tenant's erasure of the content. A purged trace therefore reads back as a skeleton, not a 404: a 404 would prove nothing.
Idempotent — purging an already-purged trace succeeds and leaves the original content_redacted_at in place.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 429
- 500
- 502
- 4XX
The purged trace skeleton
The request was malformed or failed validation.
Unauthorized
Forbidden
Trace not found
QUOTA_EXCEEDED — a requests quota on the calling API key or its project is spent for the window; Retry-After says when it reopens
Response Headers
Seconds until the quota window admits a request again
Unexpected server error — INTERNAL_ERROR, with the raw message never forwarded
The deployment's admission service is asked about this write and did not answer — ADMISSION_UNAVAILABLE; the write did not happen
The deployment's admission service refused this write — answered under the service's own 4xx status, with its code (matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$, not necessarily an ERROR_CODES key), message and meta; the write did not happen. A status this operation also declares on its own is documented there