Scheduled Tasks - Jellyfin Server

Overview

The Scheduled Tasks API provides endpoints to manage background tasks in Jellyfin. These tasks handle operations like library scans, metadata refresh, log cleanup, and other maintenance operations. Administrators can list tasks, start/stop them manually, and configure their triggers.

Get All Tasks

Retrieves a list of all scheduled tasks.

Endpoint

GET /ScheduledTasks

Authentication

Required. User must have elevated permissions (administrator).

Query Parameters

boolean

Optional filter for hidden or visible tasks

boolean

Optional filter for enabled or disabled tasks

Response

Returns an array of TaskInfo objects, sorted by task name.

string

Unique identifier for the task

string

Display name of the task

string

Description of what the task does

string

Category grouping for the task (e.g., “Library”, “Maintenance”)

string

Current state of the task (Idle, Running, Cancelling)

number

Current progress percentage if the task is running (0-100)

boolean

Whether the task is hidden from the UI

string

Task key identifier

object

Information about the last execution of this task

Show LastExecutionResult Fields

string

When the task started (ISO 8601 format)

string

When the task completed (ISO 8601 format)

string

Result status (Completed, Failed, Cancelled, Aborted)

string

Task name

string

Task key

string

Task ID

string

Error message if the task failed

string

Detailed error message if available

array

Array of triggers that schedule when this task runs

Show Trigger Fields

string

Trigger type: “Daily”, “Weekly”, “Interval”, “Startup”, “SystemEvent”

integer

Time of day in ticks (for Daily/Weekly triggers)

integer

Interval in ticks (for Interval triggers)

string

Day of week (for Weekly triggers): “Sunday”, “Monday”, etc.

integer

Maximum runtime before the task is automatically cancelled

Example Request

curl -X GET "https://your-jellyfin-server/ScheduledTasks" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Example Request with Filters

curl -X GET "https://your-jellyfin-server/ScheduledTasks?isHidden=false&isEnabled=true" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Example Response

[
  {
    "Id": "a1b2c3d4e5f6g7h8i9j0",
    "Name": "Scan Media Library",
    "Description": "Scans media libraries for new and updated files",
    "Category": "Library",
    "State": "Idle",
    "CurrentProgressPercentage": null,
    "IsHidden": false,
    "Key": "RefreshLibrary",
    "LastExecutionResult": {
      "StartTimeUtc": "2024-03-05T02:00:00.000Z",
      "EndTimeUtc": "2024-03-05T02:15:30.000Z",
      "Status": "Completed",
      "Name": "Scan Media Library",
      "Key": "RefreshLibrary",
      "Id": "a1b2c3d4e5f6g7h8i9j0"
    },
    "Triggers": [
      {
        "Type": "Daily",
        "TimeOfDayTicks": 72000000000,
        "MaxRuntimeTicks": 36000000000
      }
    ]
  },
  {
    "Id": "b2c3d4e5f6g7h8i9j0k1",
    "Name": "Clean Cache Directory",
    "Description": "Removes old files from the cache directory",
    "Category": "Maintenance",
    "State": "Idle",
    "CurrentProgressPercentage": null,
    "IsHidden": false,
    "Key": "CleanCache",
    "LastExecutionResult": {
      "StartTimeUtc": "2024-03-04T03:00:00.000Z",
      "EndTimeUtc": "2024-03-04T03:01:15.000Z",
      "Status": "Completed",
      "Name": "Clean Cache Directory",
      "Key": "CleanCache",
      "Id": "b2c3d4e5f6g7h8i9j0k1"
    },
    "Triggers": [
      {
        "Type": "Weekly",
        "TimeOfDayTicks": 108000000000,
        "DayOfWeek": "Sunday"
      }
    ]
  }
]

Response Codes

200 - Tasks retrieved successfully
403 - User does not have permission

Get Task by ID

Retrieves information about a specific scheduled task.

Endpoint

GET /ScheduledTasks/{taskId}

Authentication

Required. User must have elevated permissions (administrator).

Path Parameters

string

required

The unique identifier of the task

Response

Returns a TaskInfo object for the specified task.

Example Request

curl -X GET "https://your-jellyfin-server/ScheduledTasks/a1b2c3d4e5f6g7h8i9j0" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Example Response

{
  "Id": "a1b2c3d4e5f6g7h8i9j0",
  "Name": "Scan Media Library",
  "Description": "Scans media libraries for new and updated files",
  "Category": "Library",
  "State": "Idle",
  "CurrentProgressPercentage": null,
  "IsHidden": false,
  "Key": "RefreshLibrary",
  "LastExecutionResult": {
    "StartTimeUtc": "2024-03-05T02:00:00.000Z",
    "EndTimeUtc": "2024-03-05T02:15:30.000Z",
    "Status": "Completed",
    "Name": "Scan Media Library",
    "Key": "RefreshLibrary",
    "Id": "a1b2c3d4e5f6g7h8i9j0"
  },
  "Triggers": [
    {
      "Type": "Daily",
      "TimeOfDayTicks": 72000000000
    }
  ]
}

Response Codes

200 - Task retrieved successfully
404 - Task not found
403 - User does not have permission

Start Task

Manually starts a scheduled task.

Endpoint

POST /ScheduledTasks/Running/{taskId}

Authentication

Required. User must have elevated permissions (administrator).

Path Parameters

string

required

The unique identifier of the task to start

Response

Returns no content. The task will begin executing.

Example Request

curl -X POST "https://your-jellyfin-server/ScheduledTasks/Running/a1b2c3d4e5f6g7h8i9j0" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Response Codes

204 - Task started successfully
404 - Task not found
403 - User does not have permission

Stop Task

Stops a currently running task.

Endpoint

DELETE /ScheduledTasks/Running/{taskId}

Authentication

Required. User must have elevated permissions (administrator).

Path Parameters

string

required

The unique identifier of the task to stop

Response

Returns no content. The task will be cancelled.

Example Request

curl -X DELETE "https://your-jellyfin-server/ScheduledTasks/Running/a1b2c3d4e5f6g7h8i9j0" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Response Codes

204 - Task stopped successfully
404 - Task not found
403 - User does not have permission

Update Task Triggers

Updates the triggers for a scheduled task.

Endpoint

POST /ScheduledTasks/{taskId}/Triggers

Authentication

Required. User must have elevated permissions (administrator).

Path Parameters

string

required

The unique identifier of the task

Request Body

An array of TaskTriggerInfo objects.

string

required

Trigger type: “Daily”, “Weekly”, “Interval”, “Startup”, “SystemEvent”

integer

Time of day in ticks (for Daily/Weekly triggers). 1 hour = 36000000000 ticks

integer

Interval in ticks (for Interval triggers)

string

Day of week (for Weekly triggers): “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, “Saturday”

integer

Maximum runtime in ticks before auto-cancellation

Example Request - Daily at 2 AM

curl -X POST "https://your-jellyfin-server/ScheduledTasks/a1b2c3d4e5f6g7h8i9j0/Triggers" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "Type": "Daily",
      "TimeOfDayTicks": 72000000000,
      "MaxRuntimeTicks": 36000000000
    }
  ]'

Example Request - Weekly on Sunday at 3 AM

curl -X POST "https://your-jellyfin-server/ScheduledTasks/b2c3d4e5f6g7h8i9j0k1/Triggers" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "Type": "Weekly",
      "TimeOfDayTicks": 108000000000,
      "DayOfWeek": "Sunday"
    }
  ]'

Example Request - Every 6 Hours

curl -X POST "https://your-jellyfin-server/ScheduledTasks/c3d4e5f6g7h8i9j0k1l2/Triggers" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "Type": "Interval",
      "IntervalTicks": 216000000000
    }
  ]'

Example Request - Multiple Triggers

curl -X POST "https://your-jellyfin-server/ScheduledTasks/d4e5f6g7h8i9j0k1l2m3/Triggers" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "Type": "Daily",
      "TimeOfDayTicks": 72000000000
    },
    {
      "Type": "Startup"
    }
  ]'

Response Codes

204 - Task triggers updated successfully
404 - Task not found
403 - User does not have permission

Common Task Types

Here are some common scheduled tasks you’ll find in Jellyfin:

Library Tasks

Scan Media Library - Scans for new and updated media files
Refresh Metadata - Updates metadata for all library items
Extract Chapter Images - Extracts images for video chapters
Generate Trickplay Images - Creates preview thumbnails for videos

Maintenance Tasks

Clean Cache Directory - Removes old cached files
Clean Transcoding Directory - Cleans up temporary transcoding files
Clean Activity Log - Removes old activity log entries
Optimize Database - Optimizes the database for better performance

Update Tasks

Check for Plugin Updates - Checks if any plugins have updates available
Check for Server Updates - Checks if a new server version is available

Time Conversion Reference

Ticks are used to represent time intervals in the .NET framework. Here are common conversions:

1 second = 10,000,000 ticks
1 minute = 600,000,000 ticks
1 hour = 36,000,000,000 ticks
1 day = 864,000,000,000 ticks

Common Time Values

12:00 AM (midnight) = 0 ticks
1:00 AM = 36,000,000,000 ticks
2:00 AM = 72,000,000,000 ticks
3:00 AM = 108,000,000,000 ticks
12:00 PM (noon) = 432,000,000,000 ticks
6:00 PM = 648,000,000,000 ticks

Notes

Tasks can have multiple triggers (e.g., run daily at 2 AM AND on startup)
Some tasks may impact server performance while running
Tasks respect the MaxRuntimeTicks setting and will be cancelled if they exceed it
Use the isHidden parameter to filter out internal system tasks from the UI
Stopping a task may take a few moments as it needs to finish its current operation gracefully

​Overview

​Get All Tasks

​Endpoint

​Authentication

​Query Parameters

​Response

​Example Request

​Example Request with Filters

​Example Response

​Response Codes

​Get Task by ID

​Endpoint

​Authentication

​Path Parameters

​Response

​Example Request

​Example Response

​Response Codes

​Start Task

​Endpoint

​Authentication

​Path Parameters

​Response

​Example Request

​Response Codes

​Stop Task

​Endpoint

​Authentication

​Path Parameters

​Response

​Example Request

​Response Codes

​Update Task Triggers

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Example Request - Daily at 2 AM

​Example Request - Weekly on Sunday at 3 AM

​Example Request - Every 6 Hours

​Example Request - Multiple Triggers

​Response Codes

​Common Task Types

​Library Tasks

​Maintenance Tasks

​Update Tasks

​Time Conversion Reference

​Common Time Values

​Notes

Overview

Get All Tasks

Endpoint

Authentication

Query Parameters

Response

Example Request

Example Request with Filters

Example Response

Response Codes

Get Task by ID

Endpoint

Authentication

Path Parameters

Response

Example Request

Example Response

Response Codes

Start Task

Endpoint

Authentication

Path Parameters

Response

Example Request

Response Codes

Stop Task

Endpoint

Authentication

Path Parameters

Response

Example Request

Response Codes

Update Task Triggers

Endpoint

Authentication

Path Parameters

Request Body

Example Request - Daily at 2 AM

Example Request - Weekly on Sunday at 3 AM

Example Request - Every 6 Hours

Example Request - Multiple Triggers

Response Codes

Common Task Types

Library Tasks

Maintenance Tasks

Update Tasks

Time Conversion Reference

Common Time Values

Notes