Home

Welcome to the Sortarr wiki!

Sortarr

Deployment (Docker)

Quick start

Deploy Sortarr using Docker Compose for the easiest setup.

1. Prepare docker-compose.yaml: Clone the repository or download the docker-compose.yaml file.
2. Start the container:

   docker compose up -d

Image Sources:

• Default (GHCR): ghcr.io/jaredharper1/sortarr:latest (Recommended for release builds).
• Docker Hub: docker.io/jaredharper1/sortarr:latest.
• Architectures: Supported for linux/amd64 and linux/arm64/v8 (Apple Silicon compatible).

ACCESS AND SETUP

• URL: Open http://<host>:9595 in your browser.
• Initialization: The first visit automatically redirects to /setup, where you can configure your Sonarr/Radarr instances.

• Configuration Persistence: Ensure the ./data directory is mounted as a persistent volume (e.g., - ./data:/data). Sortarr writes configuration to /data/Sortarr.env by default (controlled by SORTARR_CONFIG_PATH).

Note: Initial library loading may take several minutes depending on library size and playback provider configuration; subsequent loads utilize the persistent cache.

Deployment (Unraid)

An Unraid template is provided at docs/unraid-template.xml to simplify deployment.

Install via template

1. Copy Template: Place the template file into Unraid’s user templates directory:
   • Source: docs/unraid-template.xml
   • Destination: /boot/config/plugins/dockerMan/templates-user/sortarr.xml
2. Add Container: In the Unraid WebUI, go to Docker → Add Container.
3. Select Template: Choose sortarr from the Template dropdown.
4. Configure Fields:
   • WebUI Port: Default is 9595 (maps to internal 8787).
   • Appdata Path: Recommended /mnt/user/appdata/sortarr (mapped to /config).
5. Advanced Settings (Optional):
   • PUID/PGID: Defaults to 99 and 100. Adjust if your appdata requires specific permissions.
   • ENV_FILE_PATH: Defaults to /config/Sortarr.env.
   • CACHE_SECONDS: Default 300.
   • Tautulli Lookups: Configure metadata lookup limits and timeouts directly in the template fields.
6. Apply: Start the container and open the WebUI.

Support: Use GitHub Issues for Unraid-specific support until a community thread is established.

The first load after startup can take a while for large libraries (especially with a playback provider configured); later loads are cached and faster.

Deployment (Windows EXE)

Sortarr can be run as a standalone Windows executable. This is ideal for users who prefer not to use Docker.

Execution

1. Download: Obtain the Sortarr.exe (PyInstaller --onefile build).
2. Run: Double-click the EXE to start the application. A terminal window will open, and the web server will start on the default port (8787).
3. Setup: Open http://localhost:8787 in your browser.

Configuration Persistence

Since single-file executables extract their contents to a temporary directory on each launch, Sortarr uses an external .env file to persist your settings:

• Automatic Initialization: On the first launch, Sortarr creates a blank .env file in the same directory as the EXE.
• Setup Page: When you save settings on the /setup page, they are written to this .env file.
• UI Hint: The exact path to the active configuration file is displayed at the bottom of the Setup page for easy reference.

Path Overrides

If you need to store the configuration elsewhere, you can set the following environment variables before running the EXE:

• SORTARR_CONFIG_PATH (Preferred): The absolute path to your configuration file (e.g., C:\Sortarr\myconfig.env).
• ENV_FILE_PATH: An alternative variable for the configuration path.

Note: Relative paths are resolved against the directory containing the EXE.

Deployment (Python / Source)

For developers or users who prefer running directly from the source code.

Prerequisites

• Python 3.10+
• pip (Python package installer)

Setup and Execution

1. Install Dependencies:

   pip install -r requirements.txt

2. Run Application:

   python app.py

3. Access: Open http://localhost:8787 in your browser.

Local Configuration

• Environment: You can set variables like PORT (default 8787) or HOST (default 0.0.0.0) in your shell before running.
• Persistence: On first launch, Sortarr creates a .env file in the project root. You can also use SORTARR_CONFIG_PATH to point to a specific file.
• Production Server: By default, Sortarr uses waitress to serve the application. Set SORTARR_USE_WAITRESS=0 only for local development/debugging with the Flask built-in server.

Internationalization

Sortarr supports multiple languages (currently English and German).

Language Selection

You can switch the interface language using the links in the top-right corner of the Setup page:

• Deutsch: Switches the UI to German.
• English: Switches the UI to English (default).

Persistence

Sortarr remembers your language choice using a combination of methods:

1. URL Parameter: Adding ?lang=de or ?lang=en to any URL will force that language for the current request.
2. Session: Your choice is saved in your browser's session cookie, persisting as long as your session is active.
3. Browser Preference: If no manual choice is made, Sortarr will attempt to match your browser's preferred language settings.

Note: Translation files are located in the translations/ directory.

Configuration Migration and Defaults

Sortarr automatically manages configuration transitions and cache integrity during version upgrades.

Automatic Migrations

On the first run after an update, Sortarr performs the following:

• Version Detection: It compares the current version against the last recorded version in Sortarr.startup.json.
• Environment Cleanup: If a version change is detected, legacy default values for variables like TAUTULLI_TIMEOUT_SECONDS or TAUTULLI_METADATA_LOOKUP_LIMIT are automatically removed from your .env file. This allows Sortarr to apply updated defaults optimized for the new version.
• Mandatory Overrides: Certain settings, such as Tautulli lookup limits, are enforced to ensure accuracy (e.g., unlimited lookups by default).
• Identifier Generation: If Plex is configured but missing a PLEX_CLIENT_ID, a unique identifier is automatically generated and saved.

Cache Invalidation

When an upgrade is detected, Sortarr triggers a mandatory cache wipe. This includes:

• Sonarr and Radarr library caches.
• Tautulli, Jellystat, and Plex metadata/history caches.
• Background refresh locks and markers.

This ensures that any data format changes or new metrics in the update are correctly populated from your media providers without interference from stale data.

Sonarr and Radarr Instances

Sortarr supports connecting to multiple Sonarr and Radarr instances simultaneously. While the Setup UI provides fields for up to three instances of each, the backend can support more if configured manually in your .env file.

Primary Instance (Required)

At minimum, one Sonarr or Radarr instance must be configured.

• SONARR_URL / RADARR_URL: The base URL of your instance.
• SONARR_API_KEY / RADARR_API_KEY: The API key (read-only is recommended).

Optional per-Instance Fields

• NAME: A friendly name (e.g., "4K", "Anime"). If multiple instances are configured, names are required to distinguish them in the UI.
• PATH_MAP: Maps container paths to host paths for UI display. Format: src:dst. Multiple entries can be separated by |, ,, or ;.
  • Example: /downloads:/mnt/media/downloads | /movies:/mnt/user/movies

Split-Network Configuration (Advanced)

For setups where Sortarr and your browser access Arr instances via different routes (e.g., Kubernetes or VPNs), you can separate the internal API URL from the external UI URL.

• *_URL_API: Internal URL used by Sortarr for HTTP requests. Falls back to *_URL.
• *_URL_EXTERNAL: External URL used for clickable links in the Sortarr UI. Falls back to *_URL_API.

Example:

SONARR_URL_API=http://sonarr.local:8989
SONARR_URL_EXTERNAL=https://sonarr.mydomain.com

Additional Instances

Configure additional instances using a numbered suffix (starting from _2).

• Sonarr: SONARR_URL_2, SONARR_API_KEY_2, SONARR_NAME_2, etc.
• Radarr: RADARR_URL_2, RADARR_API_KEY_2, RADARR_NAME_2, etc.

Tautulli (optional)

Playback stats from Tautulli can be integrated to show watch history and bitrate metrics.

• TAUTULLI_URL: The base URL of your Tautulli instance.
• TAUTULLI_API_KEY: Your Tautulli API key.

Jellystat (optional)

Playback stats from Jellystat can be integrated as an alternative or additional history source.

• JELLYSTAT_URL: The base URL of your Jellystat instance.
• JELLYSTAT_API_KEY: Your Jellystat API key.
• JELLYSTAT_LIBRARY_IDS_SONARR: Optional. Comma-separated list of Jellystat library IDs to include for Sonarr matching. If blank, all libraries containing series are used.
• JELLYSTAT_LIBRARY_IDS_RADARR: Optional. Comma-separated list of Jellystat library IDs to include for Radarr matching. If blank, all libraries containing movies are used.

Plex (optional)

Plex can be used as a media source, a history source, or for provider insights.

• PLEX_URL: The base URL of your Plex server.
• PLEX_TOKEN: Your Plex authentication token.
• PLEX_SECTION_FILTERS: Comma-separated list of section IDs to include.

Runtime Overrides

Global settings that control the server behavior, performance, and security. These can be set as environment variables or in your .env file.

Server Configuration

• PORT: The port Sortarr listens on. Default is 8787 (Docker maps 9595 externally to this port).
• HOST: The interface to bind to. Default is 0.0.0.0.
• WAITRESS_THREADS: Number of worker threads for the Waitress production server. Default is 4.
• SORTARR_USE_WAITRESS: Set to 0 to use the Flask development server (not recommended for production). Default is 1.
• SORTARR_LOG_LEVEL: Logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default is INFO.
• SORTARR_PROXY_HOPS: Number of reverse proxies to trust for X-Forwarded-* headers. Set this to 1 or 2 if you see CSRF errors behind a proxy. Default is 0.

Security

• BASIC_AUTH_USER: Optional username to enable basic authentication.
• BASIC_AUTH_PASS: Optional password for basic authentication.

Performance and Caching

• CACHE_SECONDS: Global TTL for library data in seconds. Default is 300.
• SONARR_EPISODEFILE_WORKERS: Number of threads for fetching Sonarr episode file metadata. Default is 8.
• RADARR_WANTED_WORKERS: Number of threads for fetching Radarr "wanted" (missing) movies. Default is 2 (capped at 4).
• ARR_TIMEOUT_SECONDS: Timeout for requests to Sonarr/Radarr. Default is 90.
• SORTARR_DEFER_WANTED: If True, defers fetching "wanted" data until after the main library load to speed up initial paint. Default is True.

Retries and Circuit Breaker

• ARR_BACKOFF_BASE_SECONDS: Initial delay for exponential backoff on failed Arr requests. Default is 0.5.
• ARR_BACKOFF_MAX_RETRIES: Maximum number of retries per request. Default is 2.
• ARR_CIRCUIT_FAIL_THRESHOLD: Number of failures before the circuit opens (pausing requests to that instance). Default is 3.
• ARR_CIRCUIT_OPEN_SECONDS: Duration the circuit remains open after tripping. Default is 30.

Custom Paths

• SORTARR_CONFIG_PATH: Explicit file path to your .env configuration file.
• SONARR_CACHE_PATH / RADARR_CACHE_PATH: Paths to the persistent JSON cache files for each Arr type.
• PLEX_CACHE_PATH / TAUTULLI_METADATA_CACHE: Paths to playback provider caches.

NOTE

Reverse proxy / HTTPS (Traefik, Nginx, Cloudflare, etc.)

Sortarr can be run behind a reverse proxy. In that case it may need to trust X-Forwarded-* headers so Flask correctly detects the external scheme/host (for example https://sortarr.mydomain.com). If this is not set correctly, you may see errors like "CSRF origin mismatch" during setup when accessing Sortarr via HTTPS through a proxy.

• SORTARR_PROXY_HOPS (optional)

Typical values:

• 0 Disabled
• 1 Single proxy (default)
• 2 Double proxy (e.g., Cloudflare Tunnel → Traefik → Sortarr)

Security note: If SORTARR_PROXY_HOPS is enabled, make sure Sortarr is only reachable through your reverse proxy. (Do not publish the Sortarr container port directly to the internet).

Requirements and notes:

• Basic auth is optional but recommended if exposed beyond your LAN
• Docker image runs a single Waitress process with multiple threads (default --threads=4) to keep cache/refresh state consistent
• Designed for on-demand queries with persistent caching; the UI only polls while playback matching finishes
• No database or media filesystem access required

Buttons and their actions:

• Refresh Sonarr/Radarr data reloads only the active tab's data and updates the persistent cache.
• Refresh playback data reloads both Sonarr and Radarr (and playback if configured) and updates the persistent cache, then rebuilds playback matching using cached provider data or starts a playback refresh when needed.
• Clear caches & rebuild clears all cache files and starts a full rebuild, similar to a cold start. Recommended when inaccurate data is spotted.
• Reset UI clears local UI settings and reloads using the cached data.
• Fullscreen Data Table (⛶) hides panels and expands the table to fill the screen (press Escape or ✕ to exit).

Notes continued:

• Sonarr/Radarr API keys are required for setup. Read-only keys are recommended.

• Playback stats are optional; you can configure multiple history sources (Tautulli/Jellystat/Plex) and choose a preferred history source in Setup

• Sonarr/Radarr are optional when Plex is configured as the preferred media source

• Plex can be configured alongside the history source for provider insights

• Provider option set model:

  • Media sources can be arr, plex, or both.
  • History/playback sources can be any combination of tautulli, jellystat, and plex.
  • Effective media source follows MEDIA_SOURCE_PREFERENCE (arr, plex, auto).
  • Effective history source follows HISTORY_SOURCE_PREFERENCE (tautulli, jellystat, plex, auto).
  • auto selects the first available configured source using Sortarr's deterministic order.

• Tautulli metadata lookups are cached to disk for faster matching; adjust lookup limits/workers and save cadence as needed

• Setting TAUTULLI_METADATA_LOOKUP_LIMIT=0 disables metadata matching

• Stale Tautulli refresh locks clear after TAUTULLI_REFRESH_STALE_SECONDS to avoid stuck matching

• On first run after an upgrade, Sortarr clears caches and drops legacy Tautulli default env values so new defaults apply

• When Tautulli matching runs in the background, the UI auto-refreshes to apply playback stats

• When PUID/PGID are set, the container runs as that user and will chown the config/cache paths on startup. Useful for Unraid users.

• Treat Sortarr.env as a secret; it stores API keys and optional basic auth credentials

• State-changing API requests require a CSRF token header (X-CSRF-Token) that matches the sortarr_csrf cookie; the UI handles this automatically. If you see "CSRF origin mismatch" errors, you likely need to adjust SORTARR_PROXY_HOPS from '0' to '1' or '2' depending on your reverse proxy setup.

Troubleshooting

CSRF and Reverse Proxy Issues

If you access Sortarr through a reverse proxy (e.g., Traefik, Nginx, Cloudflare Tunnel) and encounter a "CSRF origin mismatch" error when saving settings, it is likely because Sortarr does not know it is behind a proxy and is rejecting the request because the browser's Origin header doesn't match the internal URL.

The Fix: SORTARR_PROXY_HOPS

You must tell Sortarr how many proxy layers to trust so it can correctly identify its external URL from the X-Forwarded-* headers.

• Set SORTARR_PROXY_HOPS=1 if you have a single proxy (most common).
• Set SORTARR_PROXY_HOPS=2 if you have a double proxy setup (e.g., Cloudflare Tunnel → Traefik → Sortarr).

Security Note

Only enable this setting if Sortarr is behind a trusted reverse proxy. Do not expose the Sortarr container port directly to the internet if SORTARR_PROXY_HOPS is enabled, as it allows clients to spoof their origin via headers.

Mismatch Center

The Mismatch Center is a dedicated tool for identifying and resolving discrepancies between your media libraries (Sonarr/Radarr) and your playback providers (Plex, Tautulli, or Jellystat). It is accessible via the Mismatch Center button in the main toolbar (visible when at least two providers are configured).

Purpose and Functionality

• Cross-Provider Validation: Compares metadata IDs (TVDB, TMDB, IMDB) and titles across all active providers to surface mismatches.
• Root Cause Analysis: Categorizes issues into "Provider Conflicts" (where different providers report different IDs) or "Unmatched/Skipped" states.
• Diagnostic Reasons: Displays specific reasons for a failure, such as "Missing ID in Plex" or "Title mismatch in Tautulli".

Filtering and Organization

• Provider Filter: Isolate issues to a specific provider (e.g., show only items that failed to match in Tautulli).
• Status Filter: View items based on their match state:
  • Unmatched: No match was found using the available IDs.
  • Skipped: The item was intentionally skipped due to configuration limits (e.g., Tautulli lookup limit).
  • Unavailable: The provider returned no data for the item.
• Grouping: Group the results by Provider, Status, Reason, or Category to identify patterns (e.g., grouping by Reason might show a large number of items failing due to a specific library configuration issue).
• Search: Quickly find specific titles or paths within the mismatch list.

Exporting for Resolution

Use the Export CSV button to download the current filtered view. This is useful for:

• Creating a "to-do" list for manual metadata fixes in Plex or Tautulli.
• Sharing mismatch patterns with the development team for bug reporting.

Tautulli Matches

If a title shows missing or incorrect Tautulli stats, the fastest fix is to refresh the item inside Tautulli after you confirm it is matched correctly in Arr and Plex.

If you're using Plex as the playback provider (no Tautulli/Jellystat), confirm the Plex metadata IDs are correct and that Plex has recent playback history for the item.

Steps:

1. In Sonarr/Radarr, confirm the title/year and IDs are correct for the item.
2. In Plex, confirm the item metadata (title/year/IDs) matches Sonarr/Radarr.
3. In Plex, play the item for 30-60 seconds (this creates fresh Tautulli history).
4. In Tautulli, open the Now Playing entry and confirm it is the correct title.
5. In Tautulli, go to the matching library and search for the item by name.
6. If it is missing or stale, open the item and choose Media Info -> Refresh Media Info.
7. After the refresh completes, search again to confirm the item appears.
8. Back in Sortarr, click Refresh all data and wait for the load to complete.

If the title still does not match, the issue is likely missing IDs in Plex/Tautulli or a mismatch between libraries. Share the title and the Tautulli history count for that item so we can investigate further.

Tautulli UI totals vs Sortarr totals

Sortarr reads totals from the Tautulli History API (full play history). The Tautulli UI can show different totals because:

• The show page "Global Stats" totals are built from the Tautulli metadata cache, which can be incomplete for large/old libraries or after lookup limits.
• The History page footer shows the total for the current page of results, not the full filtered set.

If the show page totals look low, rebuild Tautulli's metadata cache:

1. Stop Tautulli.
2. In Tautulli, open Settings and note the "Cache Directory: X" path, then back up that directory before clearing it.
3. Start Tautulli.
4. Refresh the library in Tautulli and wait for metadata to rebuild.

After the rebuild, the show page totals should align with History totals (and with Sortarr).

User Interface and Workflows

Sortarr provides a flexible interface for analyzing large media libraries through advanced filtering, virtualization, and focused views.

Filtering

Sortarr supports multiple filtering modes to help you isolate specific subsets of your library.

Simple and Advanced Input

• Title/Path Filters: Basic wildcard-supported inputs (* and ?) for quick searching.
• Advanced Filter Input: Supports a field:value syntax for complex queries.
  • Syntax: Use field:value for standard matches (is/contains) or field>=value / field<=value for numeric comparisons.
  • Numeric Buckets: For fields like gbperhour or totalsize, integer values match whole-number buckets (e.g., gbperhour:1 matches 1.0 to 1.99).
  • Wildcards: Supports * and ? for string fields.

Filter Builder

The Filter Builder provides a structured way to create complex queries without remembering field names. It is toggled via the Chips button in the filter panel footer.

1. Category: Select the metadata field (e.g., Audio Language, Resolution, Size). The list is searchable and alphabetized.
2. Condition: Select a comparison operator (e.g., "is", "contains", "at least").
3. Value: Enter a custom value or select from a dropdown of suggested values.
4. Active Filters: Each added filter appears as a "bubble" (chip) below the builder. Clicking a bubble removes it.

Quick Chips

Quick chips provide one-click access to common filters like "Missing", "Cutoff Unmet", "Atmos", and "4K". They are grouped by category (Audio, Resolution, Source, etc.) and react to the current library tab.

Table Workflows

Fullscreen Mode (⛶)

The Fullscreen Data Table button expands the table to fill the entire browser viewport, hiding the toolbar and filter panels to maximize data visibility.

• Persistence: Fullscreen state is saved to local storage and persists across reloads.
• Exit: Click the ✕ button in the top-right or press Escape.

Column Visibility

Use the Columns menu to toggle visibility for dozens of metadata fields.

• Search: Quickly find columns by name.
• Group Toggles: Toggle entire groups like "Sonarr", "Video", or "Playback".
• CSV Columns: Enable advanced columns (e.g., Title Slug, TMDB ID) specifically for CSV export.

CSV Export

Exports the current filtered view of the active tab (Shows or Movies) to a compressed CSV file.

• Scope: Includes all currently visible columns.
• Playback Data: Playback-specific columns are included only if a playback provider (Tautulli, Jellystat, or Plex) is configured.

Media Metadata: Audio and Subtitles

Sortarr extracts and normalizes advanced media metadata from your media files via the Sonarr and Radarr APIs.

Language Detection and Normalization

• Automatic Mapping: 3-letter ISO codes (e.g., eng, deu) and 2-letter codes (e.g., en, de) are automatically mapped to full language names (e.g., "English", "German") for display and filtering.
• Mixed Languages: If a file contains multiple audio or subtitle tracks, Sortarr identifies them as "Mixed" and provides columns (Audio Languages All, Subtitle Languages All) to see the full list.
• Normalization: Language labels are normalized (e.g., English+Spanish) to ensure consistent filtering regardless of how the source Arr instance reports them.

Columns and Filters

• Audio Languages: Displays the primary audio language. Filtering supports audiolang:eng or structured selection in the Filter Builder.
• Subtitle Languages: Displays the primary subtitle language. Use sublang:eng or the "Subtitles" quick chips.
• Audio Codec & Channels: Specific columns for codecs (e.g., Atmos, EAC3, TrueHD) and channel counts (e.g., 5.1, 7.1, Stereo).
• No Subtitles: A dedicated filter (nosubs:true) and quick chip to find media missing subtitle tracks.

Quick Chips

One-click filters for common languages and codecs are available in the Quick Chips panel:

• Audio Language: English, Spanish, French, German, Japanese.
• Subtitles: English, Spanish, French, German, Japanese, No Subtitles.
• Audio Codec: Atmos, DD+, TrueHD, 5.1+, 7.1+, Stereo.

Plex Insights Drawer

The Plex Insights Drawer provides a high-level overview of your Plex server's status and library health. It is opened via the Plex Insights button in the main toolbar (visible only when Plex is configured).

Hubs and Navigation

• Library Selection: Use the chips at the top to filter insights by a specific Plex library (e.g., "Movies", "TV Shows") or view "All Libraries".
• Hub Chips: Switch between different metadata hubs like "Recently Added", "Recently Viewed", or "On Deck".
• Hub Items: Displays a list of items from the selected hub, including title, year, view count, and last viewed date.

Match Health Summary

Provides a breakdown of how well your Sonarr and Radarr libraries match your Plex library.

• Statuses: Counts for Matched, Unmatched, Skipped, Unavailable, and Pending items.
• Matched by: Lists the metadata fields used for successful matches (e.g., "Matched by TVDB ID").
• Top reasons: Surfaces common reasons for mismatches or skips.

Server Activities and Maintenance

• Activities: Real-time display of active Plex server tasks, such as library scans, metadata refreshes, or media analysis, including progress percentages.
• Butler: Monitoring of Plex Butler tasks (maintenance tasks like "Clean Old Cache Files" or "Refresh Local Metadata") with their current status and schedule.

Live Updates

The Live button in the drawer header toggles real-time updates. When enabled, Sortarr uses Server-Sent Events (SSE) to listen for Plex activity and automatically refreshes the insights when changes occur.

Grab and Import History

Sortarr provides a detailed view of the lifecycle of your media files via the History Drawer. This is useful for tracking when an item was grabbed, imported, or if a download failed.

Accessing History

• Trigger: Click the H icon (or clock icon) next to an episode title in the expanded Sonarr series view, or next to a movie title in the Radarr view.
• Scope: The history is specific to the selected episode or movie across all configured Arr instances.

Summary View (Latest vs. Previous)

When first opened, the drawer shows a summary comparing the current (Latest) file event with the one immediately preceding it (Previous).

• Event Type: Displays if the item was "Grabbed", "Imported", "Renamed", "Deleted", or "Failed".
• Deltas: Highlights changes in File Size and Custom Format Score between the two events. For example, CF +20 or +1.2 GB.
• Metadata: Shows the quality (resolution/source), date of the event, and the original source title.

Event Timeline

Clicking Show all events expands the drawer to show the full history retrieved from the Arr API.

• Event List: A chronological list of all relevant events for that item.
• Detailed Metadata: Includes:
  • Quality: The specific quality profile used (e.g., Web-DL 1080p).
  • Release Group (RG): The group responsible for the release.
  • Download ID (DL): The internal identifier for the download client task.
  • Languages: Lists the audio/subtitle languages identified during import.

Exporting History

Use the Export CSV button in the drawer header to download the full history for the item as a compressed CSV file, including raw data fields for advanced diagnostics.

UI Status Indicators

Sortarr uses visual indicators to quickly surface the health of your media instances and the status of playback data matching.

Instance Health Badges

Health badges appear in the filter panel footer when a configured Sonarr or Radarr instance reports an issue.

• Error (Red): Critical issues, such as an unreachable instance or authentication failure.
• Warning (Orange): Non-critical issues, such as indexers being down or missing root folders.
• Notice (Blue): Informational alerts or minor configuration recommendations.
• Dismissal: Clicking the × on a badge hides it for the current session. Sortarr remembers dismissed alerts to prevent repetitive clutter.
• Details: For long messages, an i button provides the full text of the alert.

Playback Match Orbs

Small colored "orbs" appear next to titles in the main table when a playback provider (Tautulli, Jellystat, or Plex) is enabled. Hovering over an orb displays the specific match reason.

• Matched (Green): The item was successfully identified in the playback history via metadata IDs or title matching.
• Potential Mismatch (Orange): An item was found but metadata IDs do not match, or multiple potential matches were found.
• Future Release (Purple): Matching was skipped because the item has not yet aired or been released.
• Not on Disk (Red): Matching was skipped because the item is missing from your local storage.
• Not Checked / Unavailable (Gray): Matching has not been performed for this item, or the provider has no data.

Developer and Integration Notes

Sortarr provides a read-only HTTP API that powers the frontend and can be used for external integrations or custom dashboards.

Authentication

If BASIC_AUTH_USER and BASIC_AUTH_PASS are configured, all /api/* endpoints require Basic Authentication. Include the Authorization: Basic <credentials> header in your requests.

CSRF Protection

For state-changing requests (POST, PUT, PATCH, DELETE), Sortarr enforces CSRF protection.

• Required Header: X-CSRF-Token
• Matching Cookie: The header value must match the value of the sortarr_csrf cookie.
• Validation: Requests without a matching token will return a 403 Forbidden error ("CSRF validation failed.").

Key API Endpoints

Endpoint	Method	Description
/api/shows	GET	Returns a JSON array of all series from Sonarr, enriched with playback stats if configured. Supports refresh=1 to trigger a background update.
/api/movies	GET	Returns a JSON array of all movies from Radarr, enriched with playback stats if configured. Supports refresh=1.
/api/shows.csv	GET	Returns series data in CSV format.
/api/movies.csv	GET	Returns movie data in CSV format.
/api/status	GET	Returns the status of the data load and playback matching. Supports lite=1 for a faster response with fewer details.
/api/config	GET	Returns the current sanitized application configuration (e.g., instance URLs, active providers).
/api/sonarr/refresh	POST	Triggers a metadata and library refresh for Sonarr. Can target a specific seriesId.
/api/radarr/refresh	POST	Triggers a metadata and library refresh for Radarr. Can target a specific movieId.
/api/tautulli/refresh	POST	Triggers a playback provider (e.g., Tautulli) library refresh.
/api/sonarr/health	GET	Returns health check alerts from all configured Sonarr instances.
/api/radarr/health	GET	Returns health check alerts from all configured Radarr instances.
/api/history	GET	Returns grab/import history for a specific item. Requires app (sonarr/radarr) and seriesId/episodeId or movieId.
/api/version	GET	Returns the current Sortarr version.

Error Handling

If an API request to a backend provider (Sonarr/Radarr) fails, Sortarr returns a 502 Bad Gateway error. A sanitized hint about the failure is provided in the X-Sortarr-Error response header.

Planned features

• Expanded efficiency views and comparisons
• Performance improvements for very large libraries
• More grouping and filtering options

Feedback and ideas are welcome.

Performance tools

Perf overlay

Press Ctrl+Shift+P to toggle a lightweight perf overlay (FPS estimate, long task count when supported, render time, visible rows, and DOM counts).

Benchmark mode (synthetic data)

You can render synthetic datasets without connecting Sonarr/Radarr:

• ?bench=1&app=radarr&rows=1000
• ?bench=1&app=radarr&rows=5000
• ?bench=1&app=radarr&rows=20000
• Add &wide=1 to show more columns.

Image previews (optional)

Sortarr can display small poster previews streamed directly from Sonarr and Radarr:

• Sonarr: series poster appears only inside the expanded series panel header.
• Radarr: movie poster appears as a hover tooltip (table row heights do not change).

Disable all image loading with ?images=0.

Features

• Sonarr series size stats (total includes specials; averages exclude specials)
• Expand Sonarr series rows to view season rollups and episode lists
• Radarr movie size stats (file size and GiB per hour)
• Bitrate metric with estimated fallback indicator
• Filter builder dropdowns with active filter bubbles (quick chips optional)
• Filter builder Category dropdown is alphabetized and searchable (desktop custom dropdown)
• Optional Arr metadata columns (status, monitored, quality profile, tags, custom formats, release group, many more)
• Sonarr/Radarr health badges to surface instance warnings
• Sonarr series metadata and wanted columns (series type, original language, genres, last aired, missing/cutoff counts)
• Sonarr chips for missing, cutoff unmet, recently grabbed, scene numbering, and airing
• Fixed-width Title column with CSS ellipsis to keep large tables stable
• Reset UI now clears in-memory and persisted filter/chip/view state in one action
• Header/layout and table-wrap sizing work is batched and memoized to reduce first-paint layout thrash
• Startup non-critical UI bindings and status polling are deferred/coalesced to reduce cold-load churn
• Fullscreen Data Table button to focus the table on small screens
• CSV export for Sonarr and Radarr (playback columns appear only when a playback provider is configured)
• Date added column for Sonarr and Radarr views
• Compressed CSV API responses for large payloads
• Multiple Sonarr/Radarr instances with optional friendly names
• Path mapping support for Docker volume paths (map container paths to host paths)
• Optional basic auth and configurable cache
• Optional playback stats from Tautulli, Jellystat, and/or Plex with a selectable preferred history source
• Playback match status orbs beside titles to flag potential mismatches (only with a playback provider configured)
• Shows/Movies top-level tabs with optional per-tab Plex library scoping (multi-select)
• Plex Insights drawer with hubs (section filter), match health summary, activities, and butler tasks (when Plex is configured)
• Audio/subtitle language columns with filters and quick chips