> ## Documentation Index
> Fetch the complete documentation index at: https://personal-92-migrate-dev-docs-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Report media timeline
> This endpoint is hit during media playback for an item. It must be hit whenever the play state changes, or in the absence of a play state change, in a regular fashion (generally this means every 10 seconds on a LAN/WAN, and every 20 seconds over cellular).
## OpenAPI
````yaml /openapi-with-code-samples.yaml post /:/timeline
openapi: 3.1.1
info:
title: Plex Media Server
version: 1.1.1
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{IP-description}.{identifier}.plex.direct:{port}
variables:
identifier:
description: The unique identifier of this particular PMS
default: 0123456789abcdef0123456789abcdef
IP-description:
description: A `-` separated string of the IPv4 or IPv6 address components
default: 1-2-3-4
port:
default: '32400'
- url: '{protocol}://{host}:{port}'
variables:
protocol:
description: The network protocol to use. Typically (`http` or `https`)
default: http
host:
description: >
The Host of the PMS.
If using on a local network, this is the internal IP address of the
server hosting the PMS.
If using on an external network, this is the external IP address for
your network, and requires port forwarding.
If using a reverse proxy, this would be the external DNS domain for
your network, and requires the proxy handle port forwarding.
default: localhost
port:
description: >
The Port number configured on the PMS. Typically (`32400`).
If using a reverse proxy, this would be the port number configured on
the proxy.
default: '32400'
- url: '{full_server_url}'
variables:
full_server_url:
description: The full manual URL to access the PMS
default: http://localhost:32400
security:
- token:
- shared user
- admin
tags:
- name: Activities
description: >
Activities provide a way to monitor and control asynchronous operations on
the server. In order to receive real-time updates for activities, a client
would normally subscribe via either EventSource or Websocket endpoints.
Activities are associated with HTTP replies via a special
`X-Plex-Activity` header which contains the UUID of the activity.
Activities are optional cancellable. If cancellable, they may be cancelled
via the `DELETE` endpoint.
- name: Butler
description: >-
The butler is responsible for running periodic tasks. Some tasks run
daily, others every few days, and some weekly. These includes database
maintenance, metadata updating, thumbnail generation, media analysis, and
other tasks.
- name: Collections
description: API Operations against the Collections
- name: Content
description: The actual content of the media provider
- name: Devices
description: >
Media grabbers provide ways for media to be obtained for a given protocol.
The simplest ones are `stream` and `download`. More complex grabbers can
have associated devices
Network tuners can present themselves on the network using the Simple
Service Discovery Protocol and Plex Media Server will discover them. The
following XML is an example of the data returned from SSDP. The
`deviceType`, `serviceType`, and `serviceId` values must remain as they
are in the example in order for PMS to properly discover the device. Other
less-obvious fields are described in the parameters section below.
Example SSDP output
```
1
0
urn:plex-tv:device:Media:1
Turing Hopper 3000
Plex, Inc.
https://plex.tv/
Turing Hopper 3000 Media Grabber
Plex Media Grabber
1
https://plex.tv
uuid:42fde8e4-93b6-41e5-8a63-12d848655811
http://10.0.0.5:8088
urn:plex-tv:service:MediaGrabber:1
urn:plex-tv:serviceId:MediaGrabber
```
- UDN: (string) A UUID for the device. This should be unique across models of a device at minimum.
- URLBase: (string) The base HTTP URL for the device from which all of the other endpoints are hosted.
- name: Download Queue
description: API Operations against the Download Queue
- name: DVRs
description: >
The DVR provides means to watch and record live TV. This section of
endpoints describes how to setup the DVR itself
- name: EPG
description: >
The EPG (Electronic Program Guide) is responsible for obtaining metadata
for what is airing on each channel and when
- name: Events
description: >
The server can notify clients in real-time of a wide range of events, from
library scanning, to preferences being modified, to changes to media, and
many other things. This is also the mechanism by which activity progress
is reported.
Two protocols for receiving the events are available: EventSource (also
known as SSE), and WebSocket.
- name: General
description: >-
General endpoints for basic PMS operation not specific to any media
provider
- name: Hubs
description: The hubs within a media provider
- name: Library
description: >-
Library endpoints which are outside of the Media Provider API. Typically
this is manipulation of the library (adding/removing sections, modifying
preferences, etc).
- name: Library Collections
description: >-
Endpoints for manipulating collections. In addition to these endpoints,
`/library/collections/:collectionId/X` will be rerouted to
`/library/metadata/:collectionId/X` and respond to those endpoints as
well.
x-displayName: 'Library: Collections'
- name: Library Playlists
description: Endpoints for manipulating playlists.
x-displayName: 'Library: Playlists'
- name: Live TV
description: |
LiveTV contains the playback sessions of a channel from a DVR device
- name: Log
description: Logging mechanism to allow clients to log to the server
- name: Play Queue
description: >-
The playqueue feature within a media provider
A play queue represents the current list of media for playback. Although
queues are persisted by the server, they should be regarded by the user as
a fairly lightweight, an ephemeral list of items queued up for playback in
a session. There is generally one active queue for each type of media
(music, video, photos) that can be added to or destroyed and replaced with
a fresh queue.
Play Queues has a region, which we refer to in this doc (partially for
historical reasons) as "Up Next". This region is defined by
`playQueueLastAddedItemID` existing on the media container. This follows
iTunes' terminology. It is a special region after the currently playing
item but before the originally-played items. This enables "Party Mode"
listening/viewing, where items can be added on-the-fly, and normal queue
playback resumed when completed.
You can visualize the play queue as a sliding window in the complete list
of media queued for playback. This model is important when scaling to
larger play queues (e.g. shuffling 40,000 audio tracks). The client only
needs visibility into small areas of the queue at any given time, and the
server can optimize access in this fashion.
All created play queues will have an empty "Up Next" area - unless the
item is an album and no `key` is provided. In this case the "Up Next" area
will be populated by the contents of the album. This is to allow queueing
of multiple albums - since the 'Add to Up Next' will insert after all the
tracks. This means that If you're creating a PQ from an album, you can
only shuffle it if you set `key`. This is due to the above implicit
queueing of albums when no `key` is provided as well as the current
limitation that you cannot shuffle a PQ with an "Up Next" area.
The play queue window advances as the server receives timeline requests.
The client needs to retrieve the play queue as the “now playing” item
changes. There is no play queue API to update the playing item.
- name: Playlist
description: Media playlists that can be created and played back
- name: Preferences
description: API Operations against the Preferences
- name: Provider
description: >-
Media providers are the starting points for the entire Plex Media Server
media library API. It defines the paths for the groups of endpoints. The
`/media/providers` should be the only hard-coded path in clients when
accessing the media library. Non-media library endpoints are outside the
scope of the media provider. See the description in See [the section in
API Info](#section/API-Info/Media-Providers) for more information on how
to use media providers.
- name: Rate
description: Operations for rating media items (thumbs up/down, star ratings, etc.)
- name: Search
description: The search feature within a media provider
- name: Status
description: >-
The status endpoints give you information about current playbacks, play
history, and even terminating sessions.
- name: Subscriptions
description: >
Subscriptions determine which media will be recorded and the criteria for
selecting an airing when multiple are available
- name: Timeline
description: The actions feature within a media provider
- name: Transcoder
description: API Operations against the Transcoder
- name: UltraBlur
description: Service provided to compute UltraBlur colors and images.
- name: Updater
description: >
This describes the API for searching and applying updates to the Plex
Media Server.
Updates to the status can be observed via the Event API.
paths:
/:/timeline:
post:
tags:
- Timeline
summary: Report media timeline
description: >
This endpoint is hit during media playback for an item. It must be hit
whenever the play state changes, or in the absence of a play state
change, in a regular fashion (generally this means every 10 seconds on a
LAN/WAN, and every 20 seconds over cellular).
operationId: report
parameters:
- $ref: '#/components/parameters/accepts'
- $ref: '#/components/parameters/X-Plex-Client-Identifier'
- $ref: '#/components/parameters/X-Plex-Product'
- $ref: '#/components/parameters/X-Plex-Version'
- $ref: '#/components/parameters/X-Plex-Platform'
- $ref: '#/components/parameters/X-Plex-Platform-Version'
- $ref: '#/components/parameters/X-Plex-Device'
- $ref: '#/components/parameters/X-Plex-Model'
- $ref: '#/components/parameters/X-Plex-Device-Vendor'
- $ref: '#/components/parameters/X-Plex-Device-Name'
- $ref: '#/components/parameters/X-Plex-Marketplace'
- name: key
description: The details key for the item.
in: query
schema:
type: string
example: /foo
- name: ratingKey
description: The rating key attribute for the item.
in: query
schema:
type: string
example: xyz
- name: state
description: The current state of the media.
in: query
schema:
type: string
enum:
- stopped
- buffering
- playing
- paused
example: playing
- name: playQueueItemID
description: If playing media from a play queue, the play queue's ID.
in: query
schema:
type: string
example: 123
- name: time
description: The current time offset of playback in ms.
in: query
schema:
type: integer
example: 0
- name: duration
description: The total duration of the item in ms.
in: query
schema:
type: integer
example: 10000
- name: continuing
description: >-
When state is `stopped`, a flag indicating whether or not the client
is going to continue playing anothe item.
in: query
schema:
$ref: '#/components/schemas/BoolInt'
example: 1
- name: updated
description: >-
Used when a sync client comes online and is syncing media timelines,
holds the time at which the playback state was last updated.
in: query
schema:
type: integer
example: 14200000
- name: offline
description: >-
Also used by sync clients, used to indicate that a timeline is being
synced from being offline, as opposed to being "live".
in: query
schema:
$ref: '#/components/schemas/BoolInt'
example: 1
- name: timeToFirstFrame
description: >-
Time in seconds till first frame is displayed. Sent only on the
first playing timeline request.
in: query
schema:
type: integer
example: 1000
- name: timeStalled
description: Time in seconds spent buffering since last request.
in: query
schema:
type: integer
example: 1000
- name: bandwidth
description: Bandwidth in kbps as estimated by the client.
in: query
schema:
type: integer
example: 100
- name: bufferedTime
description: >-
Amount of time in seconds buffered by client. Omit if computed by
`bufferedSize` below.
in: query
schema:
type: integer
example: 100
- name: bufferedSize
description: >-
Size in kilobytes of data buffered by client. Omit if computed by
`bufferedTime` above
in: query
schema:
type: integer
example: 1024
- name: X-Plex-Client-Identifier
description: Unique per client.
in: header
required: true
schema:
type: string
- name: X-Plex-Session-Identifier
description: >-
Unique per client playback session. Used if a client can playback
multiple items at a time (such as a browser with multiple tabs)
in: header
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
MediaContainer:
allOf:
- $ref: '#/components/schemas/ServerConfiguration'
- properties:
Bandwidths:
description: >-
A list of media times and bandwidths when
trascoding is using with auto adjustment of
bandwidth
properties:
Bandwidth:
items:
properties:
bandwidth:
description: The bandwidth at this time in kbps
type: integer
resolution:
description: >-
The user-friendly resolution at this
time
type: string
time:
description: >-
Media playback time where this bandwidth
started
type: integer
type: object
type: array
type: object
terminationCode:
description: >-
A code describing why the session was terminated
by the server.
type: integer
terminationText:
description: >-
A user friendly and localized text describing why
the session was terminated by the server.
type: string
type: object
type: object
'400':
$ref: '#/components/responses/400'
x-codeSamples:
- lang: go
label: PlexGO
source: "package main\n\nimport(\n\t\"context\"\n\t\"github.com/LukeHagar/plexgo/models/components\"\n\t\"github.com/LukeHagar/plexgo\"\n\t\"github.com/LukeHagar/plexgo/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := plexgo.New(\n plexgo.WithAccepts(components.AcceptsApplicationXML),\n plexgo.WithClientIdentifier(\"abc123\"),\n plexgo.WithProduct(\"Plex for Roku\"),\n plexgo.WithVersion(\"2.4.1\"),\n plexgo.WithPlatform(\"Roku\"),\n plexgo.WithPlatformVersion(\"4.3 build 1057\"),\n plexgo.WithDevice(\"Roku 3\"),\n plexgo.WithModel(\"4200X\"),\n plexgo.WithDeviceVendor(\"Roku\"),\n plexgo.WithDeviceName(\"Living Room TV\"),\n plexgo.WithMarketplace(\"googlePlay\"),\n plexgo.WithSecurity(\"\"),\n )\n\n res, err := s.Timeline.Report(ctx, operations.ReportRequest{\n Key: plexgo.Pointer(\"/foo\"),\n RatingKey: plexgo.Pointer(\"xyz\"),\n State: operations.StatePlaying.ToPointer(),\n PlayQueueItemID: plexgo.Pointer(\"123\"),\n Time: plexgo.Pointer[int64](0),\n Duration: plexgo.Pointer[int64](10000),\n Continuing: components.BoolIntTrue.ToPointer(),\n Updated: plexgo.Pointer[int64](14200000),\n Offline: components.BoolIntTrue.ToPointer(),\n TimeToFirstFrame: plexgo.Pointer[int64](1000),\n TimeStalled: plexgo.Pointer[int64](1000),\n Bandwidth: plexgo.Pointer[int64](100),\n BufferedTime: plexgo.Pointer[int64](100),\n BufferedSize: plexgo.Pointer[int64](1024),\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.Object != nil {\n // handle response\n }\n}"
- lang: java
label: PlexJava
source: |-
package hello.world;
import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.operations.*;
import dev.plexapi.sdk.models.shared.Accepts;
import dev.plexapi.sdk.models.shared.BoolInt;
import java.lang.Exception;
public class Application {
public static void main(String[] args) throws Exception {
PlexAPI sdk = PlexAPI.builder()
.accepts(Accepts.APPLICATION_XML)
.clientIdentifier("abc123")
.product("Plex for Roku")
.version("2.4.1")
.platform("Roku")
.platformVersion("4.3 build 1057")
.device("Roku 3")
.model("4200X")
.deviceVendor("Roku")
.deviceName("Living Room TV")
.marketplace("googlePlay")
.token(System.getenv().getOrDefault("TOKEN", ""))
.build();
ReportRequest req = ReportRequest.builder()
.key("/foo")
.ratingKey("xyz")
.state(State.PLAYING)
.playQueueItemID("123")
.time(0L)
.duration(10000L)
.continuing(BoolInt.True)
.updated(14200000L)
.offline(BoolInt.True)
.timeToFirstFrame(1000L)
.timeStalled(1000L)
.bandwidth(100L)
.bufferedTime(100L)
.bufferedSize(1024L)
.build();
ReportResponse res = sdk.timeline().report()
.request(req)
.call();
if (res.object().isPresent()) {
// handle response
}
}
}
- lang: typescript
label: PlexJS
source: |-
import { PlexAPI } from "@lukehagar/plexjs";
import { ReportState } from "@lukehagar/plexjs/models/operations";
import { Accepts, BoolInt } from "@lukehagar/plexjs/models/shared";
const plexAPI = new PlexAPI({
accepts: Accepts.ApplicationXml,
clientIdentifier: "abc123",
product: "Plex for Roku",
version: "2.4.1",
platform: "Roku",
platformVersion: "4.3 build 1057",
device: "Roku 3",
model: "4200X",
deviceVendor: "Roku",
deviceName: "Living Room TV",
marketplace: "googlePlay",
token: "",
});
async function run() {
const result = await plexAPI.timeline.report({
key: "/foo",
ratingKey: "xyz",
state: ReportState.Playing,
playQueueItemID: "123",
time: 0,
duration: 10000,
continuing: BoolInt.True,
updated: 14200000,
offline: BoolInt.True,
timeToFirstFrame: 1000,
timeStalled: 1000,
bandwidth: 100,
bufferedTime: 100,
bufferedSize: 1024,
});
console.log(result);
}
run();
components:
parameters:
accepts:
name: accepts
description: Indicates the client accepts the indicated media types
in: header
schema:
type: string
default: application/xml
enum:
- application/json
- application/xml
X-Plex-Client-Identifier:
name: X-Plex-Client-Identifier
x-speakeasy-name-override: Client-Identifier
in: header
description: An opaque identifier unique to the client
required: true
schema:
type: string
example: abc123
example: abc123
X-Plex-Product:
name: X-Plex-Product
x-speakeasy-name-override: Product
in: header
description: The name of the client product
schema:
type: string
example: Plex for Roku
example: Plex for Roku
X-Plex-Version:
name: X-Plex-Version
x-speakeasy-name-override: Version
in: header
description: The version of the client application
schema:
type: string
example: 2.4.1
example: 2.4.1
X-Plex-Platform:
name: X-Plex-Platform
x-speakeasy-name-override: Platform
in: header
description: The platform of the client
schema:
type: string
example: Roku
example: Roku
X-Plex-Platform-Version:
name: X-Plex-Platform-Version
x-speakeasy-name-override: Platform-Version
in: header
description: The version of the platform
schema:
type: string
example: 4.3 build 1057
example: 4.3 build 1057
X-Plex-Device:
name: X-Plex-Device
x-speakeasy-name-override: Device
in: header
description: A relatively friendly name for the client device
schema:
type: string
example: Roku 3
example: Roku 3
X-Plex-Model:
name: X-Plex-Model
x-speakeasy-name-override: Model
in: header
description: A potentially less friendly identifier for the device model
schema:
type: string
example: 4200X
example: 4200X
X-Plex-Device-Vendor:
name: X-Plex-Device-Vendor
x-speakeasy-name-override: Device-Vendor
in: header
description: The device vendor
schema:
type: string
example: Roku
example: Roku
X-Plex-Device-Name:
name: X-Plex-Device-Name
x-speakeasy-name-override: Device-Name
in: header
description: A friendly name for the client
schema:
type: string
example: Living Room TV
example: Living Room TV
X-Plex-Marketplace:
name: X-Plex-Marketplace
x-speakeasy-name-override: Marketplace
in: header
description: The marketplace on which the client application is distributed
schema:
type: string
example: googlePlay
example: googlePlay
schemas:
BoolInt:
type: integer
format: int32
enum:
- 0
- 1
example: 1
default: 0
x-speakeasy-enums:
- false
- true
ServerConfiguration:
allOf:
- $ref: '#/components/schemas/MediaContainer'
- type: object
properties:
allowCameraUpload:
type: boolean
allowChannelAccess:
type: boolean
allowMediaDeletion:
type: boolean
allowSharing:
type: boolean
allowSync:
type: boolean
allowTuners:
type: boolean
backgroundProcessing:
type: boolean
certificate:
type: boolean
companionProxy:
type: boolean
countryCode:
type: string
diagnostics:
type: string
eventStream:
type: boolean
friendlyName:
type: string
hubSearch:
type: boolean
itemClusters:
type: boolean
livetv:
type: integer
example: 7
machineIdentifier:
example: 0123456789abcdef0123456789abcdef012345678
mediaProviders:
type: boolean
multiuser:
type: boolean
musicAnalysis:
type: integer
example: 2
myPlex:
type: boolean
myPlexMappingState:
example: mapped
myPlexSigninState:
example: ok
myPlexSubscription:
type: boolean
myPlexUsername:
type: string
offlineTranscode:
example: 1
ownerFeatures:
description: >-
A comma-separated list of features which are enabled for the
server owner
type: string
platform:
type: string
platformVersion:
type: string
pluginHost:
type: boolean
pushNotifications:
type: boolean
readOnlyLibraries:
type: boolean
streamingBrainABRVersion:
type: integer
streamingBrainVersion:
type: integer
sync:
type: boolean
transcoderActiveVideoSessions:
type: integer
transcoderAudio:
type: boolean
transcoderLyrics:
type: boolean
transcoderPhoto:
type: boolean
transcoderSubtitles:
type: boolean
transcoderVideo:
type: boolean
transcoderVideoBitrates:
description: The suggested video quality bitrates to present to the user
transcoderVideoQualities:
type: string
transcoderVideoResolutions:
description: The suggested video resolutions to the above quality bitrates
updatedAt:
type: integer
updater:
type: boolean
version:
type: string
voiceSearch:
type: boolean
MediaContainer:
description: >
`MediaContainer` is the root element of most Plex API responses. It
serves as a generic container for various types of content (Metadata,
Hubs, Directories, etc.) and includes pagination information (offset,
size, totalSize) when applicable.
Common attributes: - identifier: Unique identifier for this container -
size: Number of items in this response page - totalSize: Total number of
items available (for pagination) - offset: Starting index of this page
(for pagination)
The container often "hoists" common attributes from its children. For
example, if all tracks in a container share the same album title, the
`parentTitle` attribute may appear on the MediaContainer rather than
being repeated on each track.
type: object
properties:
identifier:
type: string
offset:
description: >
The offset of where this container page starts among the total
objects available. Also provided in the `X-Plex-Container-Start`
header.
type: integer
size:
type: integer
totalSize:
description: >
The total size of objects available. Also provided in the
`X-Plex-Container-Total-Size` header.
type: integer
responses:
'400':
description: Bad Request
content:
text/html: {}
securitySchemes:
token:
name: X-Plex-Token
description: >
The token which identifies the user accessing the PMS. This can be
either:
- A traditional access token obtained from plex.tv
- A JWT token obtained through the JWT authentication flow
JWT tokens provide better security with:
- Short-lived tokens (7 days expiration)
- Public-key cryptography (ED25519)
- Better clock synchronization
- Individual device revocation capability
type: apiKey
in: header
````