Data Retention Policy
The Data Retention Policy feature allows you to automatically clean up old messages and inactive channels from your application. This helps you manage storage costs, comply with data governance requirements, and keep your application focused on relevant, recent data.
Data retention cleanup permanently deletes data. Deleted messages, channels, and their associated data (reactions, attachments, members, etc.) cannot be recovered. Make sure you understand the implications before enabling retention policies.
Overview
Stream Chat supports two types of retention policies:
- Old Messages (
old-messages): Automatically deletes messages older than a specified age. - Inactive Channels (
inactive-channels): Automatically deletes channels that have been inactive for longer than a specified period. A channel is considered inactive based on the most recent of itscreated_at,updated_at, orlast_message_attimestamps. - Inactive Channels by Type (
inactive-channels-by-type): Overrides the inactive-channels age for one channel type. See Retention Rules per Channel Type.
Key characteristics:
- Retention policies can be configured at the app level using server-side API calls or directly from the Stream Dashboard under your app's Chat settings
- The API is server-side only — all endpoints require authentication with a server-side API key
- Data is hard-deleted, not archived — deleted data cannot be recovered
- Minimum retention age is 24 hours, maximum is 5 years (43,800 hours)
- A 24-hour grace period applies after enabling or updating a policy before any cleanup begins
- Cleanup runs asynchronously in the background — after enabling a policy, it may take hours or even days for all eligible data to be removed depending on the volume of data. During this period, expired data may still appear in API responses
- Both policy types can be active simultaneously
- When a policy is enabled or updated, email notifications are sent to all admin team members
- Retention policy settings and cleanup run history are visible in the Stream Dashboard
How Long Messages Are Kept by Default
If no retention policy is configured, messages and channels are kept indefinitely. There is no default expiry, and nothing ages out on its own until you enable one of the policies above.
Data is only deleted because you asked for it, either through a retention policy or through an explicit delete call.
Who Can Change a Retention Policy
Retention policies can only be changed with your app's server-side credentials:
- The retention endpoints are server-side only. They cannot be called with a client-side token, whatever role the user has.
- Or from your app's Chat settings in the Stream Dashboard, which requires access to your Stream organization.
There is no per-user permission for retention. Who can change it is governed by who holds your server-side API secret and who has dashboard access.
Two bounds apply to every value and cannot be overridden through the API. The minimum is 24 hours and the maximum is 5 years (43,800 hours).
Contact support if your compliance requirements need a longer window. The ceiling can be raised per organization.
Retention policy changes are not currently recorded in an audit log.
The dashboard and the getRetentionPolicy endpoint show the current configuration and when it was last updated (enabled_at). The run history shows what each cleanup deleted. Neither records who made a change, or what the previous value was.
Keep your own record at the point where you call the API if you need a change history for compliance.
Confirming a Deletion Has Completed
Cleanup is asynchronous and paced, so a policy does not take effect immediately. See the 24-hour grace period and background processing described above.
Use the cleanup run history to confirm progress. Each run reports how many messages and channels it deleted.
Runs returning counts mean cleanup is working through your data. Contact support if the backlog stays flat across several runs.
Deletion and Backups
Deleted data is removed permanently from Stream's live systems and cannot be recovered through the API. This applies both to retention policy cleanup and to explicit hard deletes.
Stream also keeps operational backups for disaster recovery, as any production system does. Deleting data does not rewrite backups taken before the deletion.
Those copies expire on their own schedule, independently of your retention settings and your delete calls. Contact support if you have a regulatory requirement that depends on the exact backup window.
Setting a Retention Policy
To enable automatic cleanup, create a retention policy by specifying the policy type and the maximum age in hours.
// Delete messages older than 6 months (4,380 hours)
var response = await client.Chat.SetRetentionPolicyAsync(
new SetRetentionPolicyRequest
{
Policy = "old-messages",
MaxAgeHours = 4380,
});
// Delete channels inactive for more than 6 months
response = await client.Chat.SetRetentionPolicyAsync(
new SetRetentionPolicyRequest
{
Policy = "inactive-channels",
MaxAgeHours = 4380,
});Request Parameters
| Field | Type | Description | Required |
|---|---|---|---|
policy |
string | The policy type: old-messages, inactive-channels or inactive-channels-by-type |
Yes |
max_age_hours |
integer | Maximum age in hours before data is eligible for deletion. Must be between 24 and 43,800 (5 years). | Yes |
channel_type |
string | The channel type the rule applies to. Required with inactive-channels-by-type, rejected otherwise. |
With inactive-channels-by-type |
If a policy already exists for the specified type, calling this endpoint again will update the existing policy with the new max_age_hours value.
Retrieving Retention Policies
Retrieve all active retention policies for your application.
var response = await client.Chat.GetRetentionPolicyAsync();Cleanup run history is automatically pruned after 6 months. Runs older than 180 days are deleted at the end of each cleanup cycle. If you need long-term retention audit records, export the run history periodically using this endpoint.
Deleting a Retention Policy
Remove a retention policy to stop automatic cleanup for that policy type. Data that has already been deleted cannot be recovered.
var response = await client.Chat.DeleteRetentionPolicyAsync(
new DeleteRetentionPolicyRequest
{
Policy = "old-messages",
});Retention Rules per Channel Type
An app often mixes channels with very different lifetimes. For example, short-lived trip chats that are useless a month later, next to long-lived conversations that must be kept. A channel type rule lets each channel type have its own inactive-channels age.
How Type Rules and the App-Wide Rule Interact
The app-wide inactive-channels rule is the default. A channel type rule replaces it for that one channel type. Every channel is governed by exactly one age:
| The channel's type has... | The channel is deleted when it has been inactive for longer than... |
|---|---|
| Its own type rule | The type rule's age, whether that is shorter or longer than the app-wide age |
| No type rule, and the app has an app-wide rule | The app-wide age |
| No type rule, and the app has no app-wide rule | Never. It is not deleted by retention |
A few consequences follow from this:
- A type rule always wins, in both directions. A 30-day type rule deletes that type sooner than a 1-year app-wide rule. A 3-year type rule keeps that type longer.
- Types without a rule keep today's behavior. Adding a rule for one type does not change what happens to any other type.
- Type rules work without an app-wide rule. With type rules only, the listed types are cleaned up and every other type is kept.
- To protect a type from deletion, give it no rule and set no app-wide rule, or give it a type rule with a long age. There is no "never delete" setting.
- Removing a type rule makes that type fall back to the app-wide rule. If the app-wide age is shorter, this means more of that type becomes eligible for deletion.
- Changing the app-wide rule affects only the types that have no rule of their own.
- Type rules only cover channel deletion. The
old-messagespolicy still applies to every channel, whatever its type. If your app has anold-messagespolicy, messages older than its age are deleted in every channel, including channel types you keep with a long type rule.
Example, for an app with these rules:
| Rule | Age |
|---|---|
App-wide inactive-channels |
1 year |
inactive-channels-by-type for trip |
30 days |
inactive-channels-by-type for community |
3 years |
| Channel type | Deleted after inactivity of |
|---|---|
trip |
30 days (own rule) |
community |
3 years (own rule) |
messaging |
1 year (app-wide rule) |
| any other type | 1 year (app-wide rule) |
Grace Period
The usual 24-hour grace period applies. A type rule and the app-wide rule share it: setting, updating or removing a type rule, or setting or updating the app-wide rule, restarts the 24-hour wait for all of the app's inactive-channels rules. Nothing is deleted under any of these rules until 24 hours after the last such change. Removing the app-wide rule does not restart the wait, because it only narrows what is deleted.
Setting a Type Rule
Use the inactive-channels-by-type policy with channel_type. The channel type must already exist in your app. Calling it again for the same channel type updates that type's age.
// Delete "trip" channels after 30 days (720 hours) of inactivity
await client.chat.setRetentionPolicy({
policy: "inactive-channels-by-type",
channel_type: "trip",
max_age_hours: 720,
});SDK support for channel_type: Go v8.1.0 and later, Node.js v0.9.0 and later. Python, Ruby, PHP, .NET and Java gain the field in upcoming releases. Until then, call the server-side endpoints directly: POST /api/v2/chat/retention_policy with policy, channel_type and max_age_hours, and POST /api/v2/chat/retention_policy/delete with policy and channel_type.
The response contains the saved rule in channel_type_rule.
Listing Type Rules
getRetentionPolicy returns type rules in a separate channel_type_rules list. The policies list is unchanged: the app-wide rule still appears there as inactive-channels. channel_type_rules is omitted when the app has no type rules.
{
"policies": [
{
"policy": "inactive-channels",
"config": { "max_age_hours": 8760 },
"enabled_at": "2026-11-05T10:00:00Z"
}
],
"channel_type_rules": [
{
"channel_type": "community",
"max_age_hours": 26280,
"enabled_at": "2026-11-05T10:00:00Z"
},
{
"channel_type": "trip",
"max_age_hours": 720,
"enabled_at": "2026-11-05T10:00:00Z"
}
]
}All type rules of an app share one enabled_at, for the reason in Grace Period.
Removing a Type Rule
Delete with the same policy and channel_type. The type falls back to the app-wide rule, or is kept if there is no app-wide rule.
await client.chat.deleteRetentionPolicy({
policy: "inactive-channels-by-type",
channel_type: "trip",
});Removing a type rule sends admins a "rule removed" email, because it can make more channels eligible for deletion. Deleting a channel type that has no rule changes nothing and sends no email.
Notification Emails
When a rule is set or updated, or a type rule is removed, admins receive an email that lists every rule the app now has, what each one deletes, and the earliest time deletion can start. Removing the app-wide rule or the old-messages policy sends no email, since it only narrows what is deleted.
Cleanup Run History with Type Rules
Once an app has at least one type rule, its inactive-channels cleanup runs per channel type. Each run is recorded under a per-type policy name, and carries the type in channel_type:
Run policy |
Meaning |
|---|---|
inactive-channels@type:<channel type> |
Cleanup of a type that has its own rule |
inactive-channels@blanket:<channel type> |
Cleanup of a type that follows the app-wide rule |
A filter on {"policy": {"$eq": "inactive-channels"}} no longer matches these runs. Use $in over the run names of your channel types:
{
"filter_conditions": {
"policy": {
"$in": [
"inactive-channels@type:trip",
"inactive-channels@blanket:messaging"
]
}
}
}Viewing Cleanup Run History
You can query the history of retention cleanup runs using filters and sorting. This is useful for verifying that cleanup is working as expected and understanding how much data has been removed.
var response = await client.Chat.GetRetentionPolicyRunsAsync(
new GetRetentionPolicyRunsRequest
{
FilterConditions = new Dictionary<string, object>
{
{ "policy", new Dictionary<string, object> { { "$eq", "old-messages" } } }
},
Sort = new List<SortParamRequest>
{
new SortParamRequest { Field = "date", Direction = -1 }
},
Limit = 10,
});Request Parameters
| Parameter | Type | Description |
|---|---|---|
filter_conditions |
object | Filter runs by policy ("old-messages", "inactive-channels", or a per-type run name, see Cleanup Run History with Type Rules) and/or date (e.g., {"$gte": "2026-01-01"}) |
sort |
array | Sort by policy or date. Each entry has field and direction (-1 for descending, 1 for ascending) |
limit |
integer | Number of runs to return per page (default: 25) |
next |
string | Cursor for the next page of results (from previous response) |
prev |
string | Cursor for the previous page of results (from previous response) |
The runs endpoint uses cursor-based pagination. Use the next and prev cursors returned in the response to navigate between pages. Only one of next or prev can be specified at a time.