How to Purge Old Message History and Media in Matrix Synapse

Example scenario (illustrative only): Northstar Community, a hypothetical nonprofit, runs a Matrix Synapse homeserver. Its database and media store are growing, and the administrator wants to remove old room history and stale media without accidentally deleting current discussions or profile images. This example is not a report of a real deployment or a tested outcome.

The key is to treat message history and media as separate cleanup jobs. Synapse has a room-history purge API and separate media cleanup tools; a media retention setting can also remove files while the Matrix events that reference them remain. First decide what must remain available, then back up the database and media store, choose the appropriate method, and verify both storage areas afterward.

Decide what “old” means for your server

Before changing configuration or calling a destructive endpoint, write down a retention rule. For Northstar’s example, suppose the board approves keeping ordinary room history for 180 days, keeping local uploads under a similar policy, and treating remote media as a cache that may be fetched again if needed. A different organization might need years of retention for legal, operational, or community reasons. Those time periods are examples, not universal recommendations.

Separate the data into two categories:

• Room events: messages and other events stored in Synapse’s database. Purging events changes how far back users can browse in the room.
• Media: uploaded files, thumbnails, and cached copies of files from other homeservers. These live in the media repository or in a configured external repository.

Synapse’s official documentation describes retention policies for events and media cleanup independently. A room-history purge does not by itself prove that the media store has been cleaned, and deleting a media file does not erase the event that linked to it. Start by recording database size, media-store size, the affected rooms, and the intended cutoff. See the Synapse configuration manual.

Back up before purging

Take a database backup using the procedure recommended for your database engine, and back up the media repository or external media store as well. A database backup alone does not preserve uploaded files; a media backup alone does not restore room events. Confirm that the backups are readable and that you know how to restore them before proceeding. If Synapse runs in containers or uses separate workers, include the relevant configuration and storage volumes in your maintenance plan.

For Northstar’s hypothetical server, the administrator records the database and media-store sizes and confirms a recent restore point before touching the shared rooms. This is useful because a “cleanup” is only successful if it removes the intended data while leaving required content recoverable.

Choose scheduled retention for ongoing cleanup

If you want Synapse to keep applying a policy, configure event retention and media retention separately in the homeserver configuration. For example, an administrator could adapt this sample for a server whose approved policy is 180 days for room history and local media, with a 30-day remote-media cache:

retention:
  enabled: true
  default_policy:
    max_lifetime: 180d

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

This is an illustrative configuration, not a drop-in policy for every server. Synapse documents the event-retention feature as disabled by default. The default_policy applies to rooms that do not have an m.room.retention state event; room administrators can set room policies, while server administrators can cap policy lifetimes with the documented allowed-lifetime settings. If you need a consistent upper bound, review those controls and the room policies already in use rather than assuming the default covers every room.

Media lifetimes are based on the time since a media item was last accessed. If an item has never been accessed, Synapse uses its creation time. The setting applies to originals and thumbnails; unset or null lifetimes do not purge that media category. A remote cached item may be requested from its origin again after it has been purged. Quarantined media and locally protected media are exceptions and are not removed by these retention settings. The media cleanup runs on the Synapse process or worker that has enable_media_repo enabled. Review the current retention and media_retention reference, then apply the configuration using the normal restart or deployment procedure for your installation.

Before adopting the sample, compare its behavior with your needs. If a room message must remain readable with its attachment for 180 days, do not choose a shorter media lifetime unless you accept that the message may outlive the locally available file. Check whether your media is stored in Synapse itself or in an external media repository; Synapse’s local-media delete API does not remove media held by an external repository.

Purge older room events on demand

For a one-time cleanup, use the Synapse Purge History Admin API. This requires a server administrator access token; being an administrator of an individual room is not the same permission. Synapse recommends keeping the Admin API hidden from public view and typically making these requests from the server or a trusted administration host. Do not paste a live access token into shared shell history, tickets, or logs.

The request must specify a cutoff using an event ID or a Unix timestamp in milliseconds. The following shell example is illustrative. Replace the homeserver, room ID, token variable, and sample cutoff with values you have reviewed. The example explicitly requests deletion of local-user message events too:

export SYNAPSE_ADMIN_TOKEN='replace-with-a-server-admin-token'
PURGE_CUTOFF_MS=1760000000000  # replace with the approved UTC cutoff

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data "{\"purge_up_to_ts\": $PURGE_CUTOFF_MS, \"delete_local_events\": true}" \
  "https://matrix.example.org/_synapse/admin/v1/purge_history/!room:example.org"

Without delete_local_events: true, Synapse preserves events sent by local users by default; remote-sent events can be deleted. Room state, such as membership and topic state, is preserved. Synapse also keeps at least one message in each room. The operation can take several minutes or longer, and users cannot paginate further back through the portion being purged while it runs. The API returns a purge ID immediately; poll /_synapse/admin/v1/purge_history_status/<purge_id> until the status is complete or investigate the error if it is failed. Refer to the Purge History API documentation before selecting a cutoff. In particular, review whether removing local events is appropriate for your rooms.

Clean local media and remote cache separately

For recurring cleanup, use media_retention and choose lifetimes that match the availability you promise users. For a one-off cleanup, Synapse provides distinct endpoints:

• Local media: POST /_synapse/admin/v1/media/delete?before_ts=<timestamp_ms> removes eligible local media based on its last-use time. The API also accepts a size threshold. Profile and room-avatar media are retained by default; do not disable that protection unless you have intentionally reviewed the consequences.
• Cached remote media: POST /_synapse/admin/v1/purge_media_cache?before_ts=<timestamp_ms> removes cached remote media whose last access was before the cutoff. If a user requests a removed remote file later, Synapse can request it from the originating homeserver again.

Both endpoints use a positive Unix timestamp in milliseconds, and the media cutoff is based on last access, not simply the upload or creation date. The local-media deletion API removes the file and thumbnails from Synapse’s own storage, including locally cached copies of remote files; it does not clean up an external media repository. The response reports the number of deleted items. Check the Synapse media administration API for current parameters and endpoint details before running a request.

For the Northstar example, an administrator would first test the cutoff against the approved policy and check whether the endpoint’s returned IDs or counts match expectations. If remote cache is the only source of growth, purging local uploads would be the wrong operation. If local uploads must remain available, choose a longer local lifetime or avoid the local-media purge endpoint.

Measure the result and change course when needed

After each job, check that the purge completed successfully, review API response counts, confirm that representative rooms display the expected history boundary, and compare database and media-store usage separately. A reduction in database rows may not immediately appear as an equal reduction in operating-system disk usage; database space reclamation depends on the database engine and its maintenance procedures. Follow the database vendor’s guidance rather than deleting database files manually.

If the database shrinks but the media store does not, review media retention, the media worker with enable_media_repo, quarantine or protection status, and whether files are stored externally. If media usage falls but old messages remain, that is expected when only media was purged. If events remain unexpectedly, check whether retention is enabled, whether the room has its own retention state, whether local events were intentionally preserved, and whether the purge status is complete.

For Northstar, the success criterion is not simply “the disk is smaller.” It is that the approved old-history boundary is visible, required current messages and attachments still work, the intended media category was cleaned, and both backups remain available. If those checks fail, stop further purges and inspect the room policy, API response, worker configuration, and storage backend before widening the cleanup.

Limits to keep in mind

Retention policies are not a substitute for an organization’s legal or records-retention review. Federation means other homeservers may hold their own copies of events or media, and Synapse cannot guarantee erasure from those servers. Remote media purging removes this server’s cache; it does not delete the source file on its originating homeserver. Likewise, deleting a local event or media object from Synapse does not recall a copy another participant already downloaded.

Use scheduled retention when you need a repeatable policy; use the Admin APIs for a reviewed, targeted cleanup. Keep the two operations separate in your change record, because their success signals and effects are different.