plex-docs/docs/legacy/plex/Media Feedback.md

## Media Feedback [/:/]

This group of endpoints correspond to client feedback around an item.

### Report media timeline [GET /:/timeline{?hasMDE,key,ratingKey,state,playQueueItemID,time,duration,continuing,updated,offline,timeToFirstFrame,timeStalled,bandwidth,bufferedTime,bufferedSize,location}]

This endpoint is hit during media playback for an item. It must be hit whenever the play state changes, or in the absense 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).

In order to identify the client, the following headers are used:

- `X-Plex-Client-Identifier`: Required, unique per client.
- `X-Plex-Session-Identifier`: Optional, unique per client playback session.

Respones contains a `MediaContainer` top level XML element.  This may contain a full decision result as seen in the `video/:/transcode/universal/decision` endpoint.  If this is returned, client must stop playback and restart playback as directed by the decision.

Additional attributes include:

- `terminationCode` - Optional, a code describing why the session was terminated by the server.  See `decision` endpoint for more details.
- `terminationText` - Optional, a user friendly and localized text describing why the session was terminated by the server.

Additional child elements include:
- `Bandwidths` - Optional, an element containing one or more `Bandwidth` elements.
  - `Bandwidth` - Optional, an element containing the attribute `time` as the time of bandwidth change in milliseconds, `bandwidth` as the new bandwidth in Kbps, and `resolution` as a user presentable string indicating the new resolution.

+ Parameters
    + key: `/foo` - The details key for the item.
    + ratingKey: `xyz` - The rating key attribute for the item.
    + state: `playing` - The current state of the media.
        + Members
            + `stopped`
            + `buffering`
            + `playing`
            + `paused`
    + playQueueItemID: `123` (string, optional) - If playing media from a play queue, the play queue's ID.
    + time: `0` (milliseconds) - The current time offset of playback.
    + duration: `10000` (milliseconds) - The total duration of the item.
    + continuing: `1` - When state is `stopped`, a flag indicating whether or not the client is going to continue playing anothe item.
    + updated: `14200000` (epoch seconds) - Used when a sync client comes online and is syncing media timelines, holds the time at which the playback state was last updated.
    + offline: `1` - Also used by sync clients, used to indicate that a timeline is being synced from being offline, as opposed to being "live".
    + timeToFirstFrame: `1000` - Optional, time in seconds till first frame is displayed.  Sent only on the first playing timeline request.
    + timeStalled: `1000` (number, optional) - Time in seconds spent buffering since last request.
    + bandwidth: `100` (number, optional) - Bandwidth in kbps as estimated by the client.
    + bufferedTime: `100` (number, optional) - Amount of time in seconds buffered by client.  Omit if computed by `bufferedSize` below.
    + bufferedSize: `1024` (number, optional) - Size in kilobytes of data buffered by client.  Omit if computed by `bufferedTime` above

+ Response 200 (text/xml;charset=utf-8)

    + Body

            Normal response:
 ```xml
            <MediaContainer size="0"  />
 ```

            Admin terminated session:
```xml
            <MediaContainer size="0" terminationCode="2006" terminationText="Admin terminated playback with reason: Go Away" />
```
            Bandwidth changes included:
```xml
          <MediaContainer size="1">
              <Bandwidths>
                <Bandwidth time="0" bandwidth="15000" resolution="1080p" />
                <Bandwidth time="1050008" bandwidth="12000" resolution="1080p" />
                <Bandwidth time="1053011" bandwidth="8000" resolution="1080p" />
                <Bandwidth time="1098014" bandwidth="4000" resolution="720p" />
                <Bandwidth time="1101017" bandwidth="2000" resolution="SD" />
                <Bandwidth time="1104020" bandwidth="1000" resolution="SD" />
                <Bandwidth time="1107023" bandwidth="750" resolution="SD" />
                <Bandwidth time="1110026" bandwidth="350" resolution="SD" />
                <Bandwidth time="1113029" bandwidth="750" resolution="SD" />
                <Bandwidth time="1116032" bandwidth="1000" resolution="SD" />
                <Bandwidth time="1119035" bandwidth="4000" resolution="720p" />
                <Bandwidth time="1122038" bandwidth="10000" resolution="1080p" />
              </Bandwidths>
            </MediaContainer>
```

### Marking items watched [GET /:/scrobble{?key,uri,identifier}]

This endpoint is used to mark items watched. It may be applied to ancestor items (e.g. show or a season), in which case all descendent items are marked watched as well. A general media URI specifier may be used in advanced cases (e.g. multi-select).

+ Parameters
    + key: `/foo` - The rating key for the item.
    + uri: `library://...` - The media URI specifier. Either `key` or `uri` must be used, but not both.
    + identifier: `com.something` - The identifier for the item's provider. Allows multiplexing between multiple providers at a single endpoint.

+ Response 200


### Marking items unwatched [GET /:/unscrobble{?key,uri,identifier}]

+ Parameters
    + key: `/foo` - The rating key for the item.
    + uri: `library://...` - The media URI specifier. Either `key` or `uri` must be used, but not both.
    + identifier: `com.something` - The identifier for the item's provider. Allows multiplexing between multiple providers at a single endpoint.

+ Response 200


### Rating items [GET /:/rate{?key,identifier,rating}]

+ Parameters
    + key: `/foo` - The rating key for the item.
    + identifier: `com.something` - The identifier for the item's provider.
    + rating: `2.4` - The rating for the item.

+ Response 200