Listen for Events

Plex provides a way of pushing event notifications to a client over HTTP. This API command will open a connection to the Plex server to allow Plex to send notifications to the client when an event happens on the server.

URL

GET http://[IP address]:32400/:/eventsource/notifications?filters=[Filters]&X-Plex-Token=[PlexToken]

Parameters

NameDescription
IP addressThe IP address of the Plex Media server.
PlexTokenThe authentication Plex token.
FiltersThe filters parameter is optional. If not provided, then there will be no filter and all event notifications will be sent. The available filter options are outlined in the Filters section.

Return Status

HTTP CodeDescription
200Success - The request was successful.
401Unauthorized - The Plex token provided was not valid.

Response

When this API command is running a connection to the server is opened and remains open until the connection is closed. The content type for this command is text/event-stream, which is a server-sent event stream.

While the connection is open, the server will send event details to the client as the events happen on the server.

The server will also send a ping event every 10 seconds to ensure the client is still connected to the server.

For each event notification sent from the server, the following two fields are included:

Event Notification Fields
NameDescription
eventThe name of the event.
dataInformation associated with the event in JSON format.

The event field will always have the name of the event, however, the data field can contain no data.

ping Event

The ping event will happen every 10 seconds to ensure the client is still connected to the server. The data field contains no information for a ping event.

An example of the ping event:

event: ping
data: {}

activity Event

The activity event occurs when there is some job being run on the server. A single activity can return multiple activity notifications from the server.

An example of data returned for an activity event is shown below:

event: activity
data: {"ActivityNotification":{"event":"updated","uuid":"40874a0a-9558-4554-b070-0dae4e2f5b9c","Activity":{"uuid":"40874a0a-9558-4554-b070-0dae4e2f5b9c","type":"library.refresh.items","cancellable":false,"userID":1,"title":"Refreshing","subtitle":"Checking files","progress":0,"Context":{"key":"/library/collections/204922/children"}}}}

For an activity event, the top-level object is the ActivityNotification. This object contains fields about the activity.

ActivityNotification Fields
NameDescription
eventThe event of the activity, such as started, updated, or ended
uuidA unique identifier for the activity.
ActivityMore information about the activity. See the next table.
Activity Fields
NameDescription
uuidA unique identifier for the activity.
typeThe type of activity being performed.
cancellableIndicates whether the activity can be cancelled.
userIDThe ID associated with the user running the activity. This ID matches one from the list of accounts on the server.
titleThe title of the activity.
subtitleThe subtitle of the activity.
progressThe progress, as a percentage, of the activity.
ContextAdditional context for the activity. See the next table.
Context Fields
NameDescription
accessibleThe item associated with the activity is accessible.
analyzedThe item has been analyzed.
existsIndicates the item exists.
keyThe key for the item associated with the activity
refreshedIndicates the item has been refreshed.

As mentioned earlier, a single activity can generate multiple notifications. Each notification would show the current progress for the activity, and then a final end notification once the activity has been completed.

playing Event

The playing event will happen whenever media is played, paused, or stopped. The information in the data field will contain information about the media and the play state at the time of the event.

The playing event will return something like the following:

event: playing
data: {"PlaySessionStateNotification":{"sessionKey":"45","clientIdentifier":"4b453df1-8fb1-4aee-bfb9-3ea219fce481","guid":"","ratingKey":"217468","url":"","key":"/library/metadata/217448","viewOffset":26530,"state":"paused"}}

The top-level object in the response is the PlaySessionStateNotification object. This object contains details on the play state change from the server.

The following table lists the information included in the data field for the PlaySessionStateNotification object:

PlaySessionStateNotification Fields
NameDescription
sessionKeyUnique key for the play session.
clientIdentifierThe unique identifier associated with the client. Should match a device returned by the Get Devices API command.
guidA unique identifier for the play session.
ratingKeyThe unique key for the media item.
urlThe URL. It appears to return a blank value for media.
keyThe key to the information about the media item.
viewOffsetThe current play progress of the media in milliseconds.
playQueueIDThe ID associated to the current play queue.
stateThe play state of the media item. Valid values: playing, paused, stopped.
transcodeSessionIf the play session is being transcoded, this field will contain the unique identifier for the transcode session.

transcodeSession.update Events

When media is transcoded several transcodeSession notifications are sent. Plex will send update notifications for a transcode session using the transcodeSession.update event.

An example of data associated with this event is shown below:

event: transcodeSession.update
data: {"TranscodeSession":{"key":"/transcode/sessions/3gk8278lyxrc905hn8jgrgfr","throttled":false,"complete":false,"progress":1.2999999523162842,"size":-22,"speed":23.600000381469728,"error":false,"duration":8574912,"remaining":361,"context":"streaming","sourceVideoCodec":"h264","sourceAudioCodec":"dca","videoDecision":"copy","audioDecision":"transcode","protocol":"dash","container":"mp4","videoCodec":"h264","audioCodec":"aac","audioChannels":2,"width":1920,"height":1080,"transcodeHwRequested":true,"transcodeHwFullPipeline":false,"timeStamp":1704824487.95772,"maxOffsetAvailable":124.957,"minOffsetAvailable":0.0}}

The top-level object is the TranscodeSession, and each property of the child object will contain information about that transcode session.

The following table outlines those properties.

TranscodeSession Fields
NameDescription
keyThe unique key for the transcode session.
throttledIndicates whether the transcode session is throttled.
completeIndicates the transcode session is complete.
progressThe progress of the transcode session.
sizeThe size.
speedThe speed of the transcoding. 1.0 - the server is transcoding in real-time. Greater than 1.0 - the server is able to transcode fast enough. Less than 1.0 - the server is unable to transcode fast enough.
errorWhether there is an error.
durationThe length of time for the media item.
remainingThe remaining media to be transcoded.
contextThe context of the transcode session.
sourceVideoCodecThe source video codec.
sourceAudioCodecThe source audio codec.
videoDecisionHow the video is being handled.
audioDecisionHow the audio is being handled.
protocolThe streaming protocol.
containerThe streamining media container.
videoCodecThe streaming video codec.
audioCodecThe streaming audio codec.
audioChannelsThe streaming audio channels.
widthThe width of the media.
heightThe height of the media.
transcodeHwRequestedIndicates the hardware was requested for transcoding.
transcodeHwFullPipelineIndicates the hardware was being used.
transcodeHwRequestedIndicates the hardware was requested for transcoding.
timeStampThe current time stamp.
maxOffsetAvailableThe current media max offset.
minOffsetAvailableThe current media min offset.

transcodeSession.end Events

event: transcodeSession.end
data: {"TranscodeSession":{"key":"/transcode/sessions/3gk8278lyxrc905hn8jgrgfr","throttled":false,"complete":false,"progress":1.600000023841858,"size":-22,"speed":33.5,"error":false,"duration":8574912,"remaining":291,"context":"streaming","sourceVideoCodec":"h264","sourceAudioCodec":"dca","videoDecision":"copy","audioDecision":"transcode","protocol":"dash","container":"mp4","videoCodec":"h264","audioCodec":"aac","audioChannels":2,"width":1920,"height":1080,"transcodeHwRequested":true,"transcodeHwFullPipeline":false,"timeStamp":1704824487.95772}}

The top-level object is the TranscodeSession, and each property of the child object will contain information about that transcode session.

The following table outlines those properties.

TranscodeSession Fields
NameDescription
keyThe unique key for the transcode session.
throttledIndicates whether the transcode session is throttled.
completeIndicates the transcode session is complete.
progressThe progress of the transcode session.
sizeThe size.
speedThe speed of the transcoding. 1.0 - the server is transcoding in real-time. Greater than 1.0 - the server is able to transcode fast enough. Less than 1.0 - the server is unable to transcode fast enough.
errorWhether there is an error.
durationThe length of time for the media item.
remainingThe remaining media to be transcoded.
contextThe context of the transcode session.
sourceVideoCodecThe source video codec.
sourceAudioCodecThe source audio codec.
videoDecisionHow the video is being handled.
audioDecisionHow the audio is being handled.
protocolThe streaming protocol.
containerThe streamining media container.
videoCodecThe streaming video codec.
audioCodecThe streaming audio codec.
audioChannelsThe streaming audio channels.
widthThe width of the media.
heightThe height of the media.
transcodeHwRequestedIndicates the hardware was requested for transcoding.
transcodeHwFullPipelineIndicates the hardware was being used.
transcodeHwRequestedIndicates the hardware was requested for transcoding.
timeStampThe current time stamp.

Remarks

Filters

To return specific events, you can apply filters to the API command. If a filter parameter is not passed into the command, then all events will be pushed to the client.

The following table lists valid filters that can be passed into the command.

Event Notification Filter Values
NameDescription
activityAn activity is happening on the server.
playingWhen media is playing, paused, or stopped.
transcodeSession.startA transcoding session is started.
transcodeSession.updateA transcoding session has been updated.
transcodeSession.endA transcoding session has ended.

When passing in multiple filters, separate each filter value with a comma.

/:/eventsource/notifications?filters=activity,playing,transcodeSession.start,transcodeSession.update,transcodeSession.end

Examples

curl -X GET http://[IP address]:32400/:/eventsource/notifications?filters=[Filters]&X-Plex-Token=[PlexToken]
import requests
plex_url = http://[IP address]:32400/:/eventsource/notifications?filters=[Filters]&X-Plex-Token=[PlexToken]
response = requests.get(plex_url)
print(response.text)
$response = Invoke-RestMethod 'http://[IP address]:32400/:/eventsource/notifications?filters=[Filters]&X-Plex-Token=[PlexToken]' -Method 'GET'
Write-Output $response
Subscribe
Display