Deleterr

Deleterr distinguishes between notifications intended for administrators and those intended for end-users:

• Run Summary: Sent to Admins to report exactly what was deleted during a specific run.
• Leaving Soon: Sent to Users to alert them about content scheduled for deletion so they can watch it before it is removed.

Important: leaving_soon notifications are configured separately from run summary notifications and do not inherit provider settings from the parent notifications block.

Matching Logic

• Movies are matched using their TMDB ID.
• TV Shows are matched using their TVDB ID.

Known Limitations

• Authentication: Deleterr authenticates using the Client ID only (no OAuth). Consequently, Favorites lists can only be accessed if the user's profile is set to public.
• Unsupported Lists: Periodic lists such as watched/weekly or collected/monthly are not currently supported.

Deleterr follows a five-step lifecycle to manage your media:

1. Connects: Establishes connections to your Plex, Tautulli, and Radarr/Sonarr instances.
2. Analyzes: Evaluates watch history and media metadata.
3. Filters: Applies your rules (e.g., watched status, age, and exclusions) to identify candidates for deletion.
4. Deletes: Executes the deletion of matching media through the Radarr or Sonarr APIs.
5. Optionally triggers: Performs post-deletion actions like triggering library scans or adding list exclusions.

When using the last_watched field, unwatched items always sort first, regardless of whether you set the order to asc or desc.

The order setting only controls how watched items are sorted among themselves. This behavior ensures that unwatched content is prioritized for deletion before recently-watched content.

WARNING: DATA LOSS RISK

DO NOT USE THIS WITH MEDIA CONTENT YOU CAN'T AFFORD TO LOSE.

To mitigate risk, it is recommended to turn on the recycle bin in your Sonarr/Radarr settings. This allows for file recovery if a deletion was unintended. Note that the recycle bin is not recommended for remote mounts.

You can define how Seerr/Overseerr requests affect deletion logic at the library level using the mode option:

• exclude (default): Protects requested media from deletion. Use this to ensure content users asked for is kept.
• include_only: Only deletes media that was requested through Seerr. All other content is skipped.

# Protect requested media
exclude:
  seerr:
    mode: "exclude"

# Only delete requested media
exclude:
  seerr:
    mode: "include_only"

Deleterr supports several types of Trakt lists for exclusions. Ensure the URLs follow these patterns:

• Official Lists: e.g., https://trakt.tv/movies/trending, https://trakt.tv/shows/popular.
• User Watchlists: https://trakt.tv/users/yourusername/watchlist.
• User Favorites: https://trakt.tv/users/yourusername/favorites (Note: The user's profile must be public).
• Custom User Lists: Any public list, e.g., https://trakt.tv/users/username/lists/list-slug.

You can sort by multiple fields by providing a comma-separated list in the field key. The first field is the primary sort, and subsequent fields act as tie-breakers.

Provide a comma-separated list in the order key to specify the direction for each field. If you provide fewer orders than fields, the last order in the list is reused for all remaining fields.

# Sort by last_watched descending, then size descending
sort:
  field: "last_watched,size"
  order: "desc,desc"

# Sort by last_watched, size, and title, all descending (reusing last order)
sort:
  field: "last_watched,size,title"
  order: "desc"

Exclusions are used to protect specific media items from being deleted. If an item matches any exclusion rule, it is skipped entirely. Deleterr uses OR logic for exclusions, meaning a single match is sufficient to protect an item.

Exclusions are configured within a libraries block using the exclude key. You can combine Metadata, Radarr, Sonarr, and Integration exclusions within the same library block.

libraries:
  - name: "Movies"
    radarr: "Radarr"
    action_mode: "delete"
    exclude:
      # Rules go here

Title Matching

JustWatch attempts to match your media to its database using:

1. Exact title + exact year
2. Case-insensitive title + exact year
3. Case-insensitive title + 1-year tolerance (to account for regional release date variations)

If no match is found, the item is not excluded.

Rate Limiting

If JustWatch returns an HTTP 429 (Too Many Requests) error:

• Deleterr logs a warning on the first occurrence.
• Subsequent rate-limited items are silently skipped.
• The rate limit resets automatically.

Tip: If you hit rate limits frequently, reduce max_actions_per_run or run Deleterr less often.