Stats API

Cleanuparr provides a stats endpoint that exposes aggregated application statistics. This is designed for integration with dashboard tools like Homepage, Homarr, or any tool that can consume JSON APIs.

Authentication

API Key

This endpoint requires authentication. You can authenticate using your API key in one of two ways:

Header (recommended):

curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:11011/api/stats

Query parameter:

curl http://localhost:11011/api/stats?apikey=YOUR_API_KEY

You can find your API key in the Cleanuparr UI under Account Settings.

Note

JWT Bearer tokens are also supported for browser-based access.

Endpoint

GET /api/stats

Returns aggregated statistics including events, strikes, job runs, and health status.

Query Parameters:

Parameter	Type	Default	Description
`hours`	integer	`24`	Timeframe in hours (range: 1–720)
`includeEvents`	integer	`0`	Number of recent events to include (range: 0–100). Omitted from response when 0.
`includeStrikes`	integer	`0`	Number of recent strikes to include (range: 0–100). Omitted from response when 0.

Examples:

# Last 24 hours (default)
curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:11011/api/stats

# Last hour
curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:11011/api/stats?hours=1

# Last 7 days
curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:11011/api/stats?hours=168

# Include 5 recent events and 5 recent strikes
curl -H "X-Api-Key: YOUR_API_KEY" "http://localhost:11011/api/stats?includeEvents=5&includeStrikes=5"

Note

If BASE_PATH is set, include it in the URL: http://localhost:11011/cleanuparr/api/stats

Response Reference

events

Event statistics within the specified timeframe.

{
  "totalCount": 42,
  "byType": {
    "FailedImportStrike": 5,
    "StalledStrike": 12,
    "QueueItemDeleted": 8,
    "DownloadCleaned": 6
  },
  "bySeverity": {
    "Information": 20,
    "Warning": 15,
    "Error": 7
  },
  "timeframeHours": 24,
  "recentItems": [
    {
      "id": "...",
      "timestamp": "2025-01-15T12:00:00Z",
      "eventType": "StalledStrike",
      "message": "Strike issued for stalled download",
      "severity": "Warning",
      "data": null
    }
  ]
}

totalCount — Total number of events in the timeframe
byType — Events grouped by type (only types with events are included)
bySeverity — Events grouped by severity level
timeframeHours — The requested timeframe
recentItems — Recent event records (only present when includeEvents > 0)

strikes

Strike statistics within the specified timeframe.

{
  "totalCount": 23,
  "byType": {
    "Stalled": 8,
    "FailedImport": 5,
    "SlowSpeed": 4,
    "SlowTime": 3,
    "DownloadingMetadata": 3
  },
  "itemsRemoved": 10,
  "timeframeHours": 24,
  "recentItems": [
    {
      "id": "...",
      "type": "Stalled",
      "createdAt": "2025-01-15T12:00:00Z",
      "downloadId": "abc123",
      "title": "Some.Download.Title"
    }
  ]
}

totalCount — Total number of strikes issued in the timeframe
byType — Strikes grouped by type (only types with strikes are included)
itemsRemoved — Number of download items removed that had strikes in the timeframe
recentItems — Recent strike records with download info (only present when includeStrikes > 0)

jobs

Job run statistics within the specified timeframe.

{
  "byType": {
    "QueueCleaner": {
      "totalRuns": 48,
      "completed": 46,
      "failed": 2,
      "lastRunAt": "2025-01-15T12:00:00Z",
      "nextRunAt": "2025-01-15T12:30:00Z"
    },
    "MalwareBlocker": {
      "totalRuns": 48,
      "completed": 48,
      "failed": 0,
      "lastRunAt": "2025-01-15T12:00:00Z",
      "nextRunAt": "2025-01-15T12:30:00Z"
    }
  },
  "timeframeHours": 24
}

byType — Stats per job type (QueueCleaner, MalwareBlocker, DownloadCleaner, BlacklistSynchronizer)
totalRuns — Total executions in the timeframe
completed / failed — Breakdown by outcome
lastRunAt — Timestamp of the most recent run
nextRunAt — When this job is next scheduled to run

health

Current health status of all configured download clients and arr instances. Health data is cached and updated every ~5 minutes by a background service.

{
  "downloadClients": [
    {
      "id": "...",
      "name": "qBittorrent",
      "type": "qBittorrent",
      "isHealthy": true,
      "lastChecked": "2025-01-15T12:00:00Z",
      "responseTimeMs": 45.2,
      "errorMessage": null
    }
  ],
  "arrInstances": [
    {
      "id": "...",
      "name": "Sonarr",
      "type": "Sonarr",
      "isHealthy": true,
      "lastChecked": "2025-01-15T12:00:00Z",
      "errorMessage": null
    }
  ]
}

downloadClients — Health of each enabled download client
arrInstances — Health of each enabled arr instance (Sonarr, Radarr, Lidarr, Readarr, Whisparr)

Important

Health data reflects the last background check (~5 minute interval). It does not perform live checks on each request, keeping the endpoint fast for frequent polling.

Dashboard Integration

Homepage Example

Homepage can use the customapi widget to display Cleanuparr stats:

- Cleanuparr:
    icon: cleanuparr.png
    href: http://localhost:11011
    description: Arr Cleanup Service
    widget:
      type: customapi
      url: http://localhost:11011/api/stats
      headers:
        X-Api-Key: YOUR_API_KEY
      mappings:
        - field: events.totalCount
          label: Events (24h)
          format: number
        - field: strikes.totalCount
          label: Strikes (24h)
          format: number
        - field: strikes.itemsRemoved
          label: Removed
          format: number

You can reference any field in the response using dot notation (e.g., jobs.byType.QueueCleaner.failed).

To change the timeframe, add a query parameter to the URL: http://localhost:11011/api/stats?hours=168 for a weekly view.

Other Dashboard Tools

Any tool that can fetch and parse JSON can use this endpoint. The response is a flat, predictable JSON structure designed for easy field mapping.

Key fields for dashboards:

events.totalCount — Total events in timeframe
strikes.totalCount — Total strikes in timeframe
strikes.itemsRemoved — Downloads removed
jobs.byType.<JobType>.failed — Failed job runs
jobs.byType.<JobType>.nextRunAt — Next scheduled run
health.downloadClients[0].isHealthy — First download client health
health.arrInstances[0].isHealthy — First arr instance health