.png&w=640&q=75){kind=small}
Overview
When you configure a checkpointer TTL with strategy: "delete" in your langgraph.json, a background sweeper process running inside the LangGraph server will automatically clean up idle threads after a specified period of inactivity. This article explains exactly when deletion happens, what gets deleted, and what doesn't.
Configuration
In your langgraph.json, add a checkpointer.ttl block with three fields:
- default_ttl: How many minutes of inactivity before a thread becomes eligible for deletion. For example, 1440 = 24 hours.
- sweep_interval_minutes: How often a background process checks for expired threads. For example, 10 = every 10 minutes.
- strategy: What to do when a thread expires. "delete" removes everything.
When is the TTL enforced?
Thread deletion does NOT happen the instant the TTL expires. Instead, a background sweeper runs on a timer (every sweep_interval_minutes) and queries for threads whose expiration time has passed. This means the actual deletion happens sometime between the TTL expiring and the next sweep cycle completing.
The TTL clock resets every time there is new activity on the thread (e.g., a new run or checkpoint). So the countdown always starts from the MOST RECENT ACTIVITY, not from when the thread was first created.
Step-by-step example
Settings: default_ttl = 60 (1 hour), sweep_interval_minutes = 10.
1. T=0:00 -- User sends first message. Checkpoint C1 is created. TTL is set. Thread expires at 1:00.
2. T=0:25 -- User sends second message. Checkpoint C2 is created. TTL clock RESETS. Thread now expires at 1:25.
3. T=0:50 -- User sends third message. Checkpoint C3 is created. TTL clock RESETS. Thread now expires at 1:50.
4. T=1:00 -- Sweeper runs. Thread expires at 1:50, still in the future. No action.
5. T=1:10 -- Sweeper runs. Still not expired. No action.
6. T=1:20 -- Sweeper runs. Still not expired. No action.
7. (No more user activity on this thread.)
8. T=2:00 -- Sweeper runs. Thread expired at 1:50, which is now in the past. THREAD IS DELETED.
The thread, all three checkpoints (C1, C2, C3), all writes, and all Platform run records are now gone.
What gets deleted
When a thread is deleted via TTL, the following data is removed from the Postgres database:
- The thread itself
- All checkpoints associated with the thread
- All checkpoint writes
- All Platform run records for that thread
These are all cascade-deleted in a single operation.
What does not get deleted
LangSmith traces are NOT affected. Traces live in LangSmith's own backend, which is a completely separate system from the database where threads are stored. After a thread is cleaned up by TTL, the traces from those runs are still fully intact and queryable in LangSmith. LangSmith traces follow their own retention policies independently.
Other things to know
- Only new threads are affected. The TTL only applies to threads created after the configuration is deployed. Pre-existing threads are not retroactively given a TTL.
- Per-thread overrides are supported. You can set a custom TTL on individual threads via the API (on create or patch), overriding the global default_ttl.
- Multi-replica safety. In horizontally scaled deployments, only one replica performs the sweep at a time (coordinated via a distributed lock), so threads are not double-processed.
- "delete" vs "keep_latest". The "delete" strategy removes the entire thread. If you want to keep the thread and its most recent checkpoint but prune older checkpoint history, use "keep_latest" instead.
Related Docs
- Configuring thread and checkpoint TTL: https://docs.langchain.com/langsmith/configure-ttl
- Scaling your agent server: https://docs.langchain.com/langsmith/agent-server-scale