Run Refresh Local Metadata Task

There are a number of tasks that can be scheduled to run on a Plex server. This API command will run the refresh local metadata task.


POST http://{ip_address}:32400/butler/RefreshLocalMedia?X-Plex-Token={plex_token}


ip_addressThe IP address of the Plex Media server.
plex_tokenThe Plex token.

Return Status

HTTP CodeDescription
200Success - The task has started successfully.
202Accepted - The task is currently running.
401Unauthorized - The Plex token provided was not valid.


No response is returned by the command. The status code will indicate whether the refresh local metadata task was started successfully.


When a new subtitle or cover art is added, the local media agent will find it and add it into the library. This when the server detects a change in the directory, but it does add a few seconds when selecting an item in a library before it can appear.

This API command can help speed things up by running the task to update the libraries with local metadata, so when the item is selected, it will automatically show the local media files.

Since this task is related to local metadata, it does not download metadata for any media.

The scheduled tasks are defined in the Plex settings, and will run during a specified time window. This API command will run manually start the task.

When starting a task, Plex will use the following criteria:

  • If a task is not scheduled to run on the current day, it will be skipped.
  • The task will start immediately if it is to run at a random time during a configured window, and this command is not run within that window.
  • The task will be scheduled to run if it is to run at a random time during a configured window, and this command is run within that window.
  • The task will run immediately if it is outside the configured window.


curl -X POST http://{ip_address}:32400/butler/RefreshLocalMedia?X-Plex-Token={plex_token}
import requests
plex_url = http://{ip_address}:32400/butler/RefreshLocalMedia?X-Plex-Token={plex_token}
response =
$response = Invoke-RestMethod 'http://{ip_address}:32400/butler/RefreshLocalMedia?X-Plex-Token={plex_token}' -Method 'POST'
Write-Output $response