Skip to main content
POST
/
:
/
timeline
PlexGO
package main

import(
	"context"
	"github.com/LukeHagar/plexgo/models/components"
	"github.com/LukeHagar/plexgo"
	"github.com/LukeHagar/plexgo/models/operations"
	"log"
)

func main() {
    ctx := context.Background()

    s := plexgo.New(
        plexgo.WithAccepts(components.AcceptsApplicationXML),
        plexgo.WithClientIdentifier("abc123"),
        plexgo.WithProduct("Plex for Roku"),
        plexgo.WithVersion("2.4.1"),
        plexgo.WithPlatform("Roku"),
        plexgo.WithPlatformVersion("4.3 build 1057"),
        plexgo.WithDevice("Roku 3"),
        plexgo.WithModel("4200X"),
        plexgo.WithDeviceVendor("Roku"),
        plexgo.WithDeviceName("Living Room TV"),
        plexgo.WithMarketplace("googlePlay"),
        plexgo.WithSecurity("<YOUR_API_KEY_HERE>"),
    )

    res, err := s.Timeline.Report(ctx, operations.ReportRequest{
        Key: plexgo.Pointer("/foo"),
        RatingKey: plexgo.Pointer("xyz"),
        State: operations.StatePlaying.ToPointer(),
        PlayQueueItemID: plexgo.Pointer("123"),
        Time: plexgo.Pointer[int64](0),
        Duration: plexgo.Pointer[int64](10000),
        Continuing: components.BoolIntOne.ToPointer(),
        Updated: plexgo.Pointer[int64](14200000),
        Offline: components.BoolIntOne.ToPointer(),
        TimeToFirstFrame: plexgo.Pointer[int64](1000),
        TimeStalled: plexgo.Pointer[int64](1000),
        Bandwidth: plexgo.Pointer[int64](100),
        BufferedTime: plexgo.Pointer[int64](100),
        BufferedSize: plexgo.Pointer[int64](1024),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Object != nil {
        // handle response
    }
}
{
  "MediaContainer": {
    "identifier": "<string>",
    "offset": 123,
    "size": 123,
    "totalSize": 123,
    "allowCameraUpload": true,
    "allowChannelAccess": true,
    "allowMediaDeletion": true,
    "allowSharing": true,
    "allowSync": true,
    "allowTuners": true,
    "backgroundProcessing": true,
    "certificate": true,
    "companionProxy": true,
    "countryCode": "<string>",
    "diagnostics": "<string>",
    "eventStream": true,
    "friendlyName": "<string>",
    "hubSearch": true,
    "itemClusters": true,
    "livetv": 7,
    "machineIdentifier": "<any>",
    "mediaProviders": true,
    "multiuser": true,
    "musicAnalysis": 2,
    "myPlex": true,
    "myPlexMappingState": "<any>",
    "myPlexSigninState": "<any>",
    "myPlexSubscription": true,
    "myPlexUsername": "<string>",
    "offlineTranscode": "<any>",
    "ownerFeatures": "<string>",
    "platform": "<string>",
    "platformVersion": "<string>",
    "pluginHost": true,
    "pushNotifications": true,
    "readOnlyLibraries": true,
    "streamingBrainABRVersion": 123,
    "streamingBrainVersion": 123,
    "sync": true,
    "transcoderActiveVideoSessions": 123,
    "transcoderAudio": true,
    "transcoderLyrics": true,
    "transcoderPhoto": true,
    "transcoderSubtitles": true,
    "transcoderVideo": true,
    "transcoderVideoBitrates": "<any>",
    "transcoderVideoQualities": "<string>",
    "transcoderVideoResolutions": "<any>",
    "updatedAt": 123,
    "updater": true,
    "version": "<string>",
    "voiceSearch": true,
    "Bandwidths": {
      "Bandwidth": [
        {
          "bandwidth": 123,
          "resolution": "<string>",
          "time": 123
        }
      ]
    },
    "terminationCode": 123,
    "terminationText": "<string>"
  }
}

Authorizations

​
X-Plex-Token
string
header
required

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

Headers

​
accepts
enum<string>
default:application/xml

Indicates the client accepts the indicated media types

Available options:
application/json,
application/xml
​
X-Plex-Client-Identifier
string
required

Unique per client.

​
X-Plex-Product
string

The name of the client product

Example:

"Plex for Roku"

​
X-Plex-Version
string

The version of the client application

Example:

"2.4.1"

​
X-Plex-Platform
string

The platform of the client

Example:

"Roku"

​
X-Plex-Platform-Version
string

The version of the platform

Example:

"4.3 build 1057"

​
X-Plex-Device
string

A relatively friendly name for the client device

Example:

"Roku 3"

​
X-Plex-Model
string

A potentially less friendly identifier for the device model

Example:

"4200X"

​
X-Plex-Device-Vendor
string

The device vendor

Example:

"Roku"

​
X-Plex-Device-Name
string

A friendly name for the client

Example:

"Living Room TV"

​
X-Plex-Marketplace
string

The marketplace on which the client application is distributed

Example:

"googlePlay"

​
X-Plex-Session-Identifier
string

Unique per client playback session. Used if a client can playback multiple items at a time (such as a browser with multiple tabs)

Query Parameters

​
key
string

The details key for the item.

​
ratingKey
string

The rating key attribute for the item.

​
state
enum<string>

The current state of the media.

Available options:
stopped,
buffering,
playing,
paused
​
playQueueItemID
string

If playing media from a play queue, the play queue's ID.

​
time
integer

The current time offset of playback in ms.

​
duration
integer

The total duration of the item in ms.

​
continuing
enum<integer>

When state is stopped, a flag indicating whether or not the client is going to continue playing anothe item.

Available options:
0,
1
​
updated
integer

Used when a sync client comes online and is syncing media timelines, holds the time at which the playback state was last updated.

​
offline
enum<integer>

Also used by sync clients, used to indicate that a timeline is being synced from being offline, as opposed to being "live".

Available options:
0,
1
​
timeToFirstFrame
integer

Time in seconds till first frame is displayed. Sent only on the first playing timeline request.

​
timeStalled
integer

Time in seconds spent buffering since last request.

​
bandwidth
integer

Bandwidth in kbps as estimated by the client.

​
bufferedTime
integer

Amount of time in seconds buffered by client. Omit if computed by bufferedSize below.

​
bufferedSize
integer

Size in kilobytes of data buffered by client. Omit if computed by bufferedTime above

Response

OK

​
MediaContainer
object

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.