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={plex_token}

Parameters

Return Status

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:

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.

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:

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.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.

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.

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={plex_token}

import requests
plex_url = http://{ip_address}:32400/:/eventsource/notifications?filters={filters}&X-Plex-Token={plex_token}
response = requests.get(plex_url)
print(response.text)

$response = Invoke-RestMethod 'http://{ip_address}:32400/:/eventsource/notifications?filters={filters}&X-Plex-Token={plex_token}' -Method 'GET'
Write-Output $response

Script examples

Below are a list of post and articles that provide an example that use this API endpoint:

• How to Stop a Transcode Session Automatically