How do I delete traces and runs in LangSmith based on custom retention periods?
Last updated: May 6, 2026
Context
When managing data retention in LangSmith, you may need to implement custom deletion policies for traces and runs, particularly in multi-tenant environments where different retention periods are required for different tenants.
Answer
There are several methods available for deleting traces and runs in LangSmith:
1. Using the API (Soft Delete)
The primary method is using the LangSmith API's delete endpoint, which implements a soft delete mechanism:
Deletions are marked as pending first (HTTP 202 response)
Actual deletion occurs during non-peak usage times, typically within a few hours
This method allows for potential undoing of deletions
When deleting traces, all child runs with matching trace_id will also be deleted
2. Using the API (Hard Delete)
Permanently removes inputs, outputs, and metadata from ALL dataset versions
Complete data removal when compliance requires zero-out across all versions
Add
"hard_delete": trueto the query parameters
Note: Hard deletion is currently only available for datasets and examples, not for traces and runs. For implementing custom retention periods, it's recommended to use the soft delete mechanism and schedule deletions slightly earlier than the target retention period to account for the deletion processing time.
3. Using the Direct Delete Script
For more immediate deletions, you can use the provided helper script that directly deletes traces from ClickHouse:
Available at: delete_trace_by_id.sh
Bypasses the API and directly removes data from ClickHouse
This is equivalent to a hard deletion and is irreversible