Tautulli API Reference
JonnyWong16 edited this page Jul 13, 2023
·
21 revisions
The API endpoint is
http://IP_ADDRESS:PORT + [/HTTP_ROOT] + /api/v2?apikey=$apikey&cmd=$command
Example:
http://localhost:8181/api/v2?apikey=66198313a092496b8a725867d2223b5f&cmd=get_metadata&rating_key=153037
Response example (default json)
{
"response": {
"data": [
{
"loglevel": "INFO",
"msg": "Signal 2 caught, saving and exiting...",
"thread": "MainThread",
"time": "22-sep-2015 01:42:56 "
}
],
"message": null,
"result": "success"
}
}
General optional parameters:
out_type: "json" or "xml"
callback: "pong"
debug: 1
Add a new notification agent.
Required parameters:
agent_id (int): The newsletter type to add
Optional parameters:
None
Returns:
None
Add a new notification agent.
Required parameters:
agent_id (int): The notification agent to add
Optional parameters:
None
Returns:
None
Get to the chopper!
Create a manual backup of the config.ini file.
Create a manual backup of the plexpy.db file.
Delete all Tautulli history for a specific library.
Required parameters:
server_id (str): The Plex server identifier of the library section
section_id (str): The id of the Plex library section
Optional parameters:
row_ids (str): Comma separated row ids to delete, e.g. "2,3,8"
Returns:
None
Delete all Tautulli history for a specific user.
Required parameters:
user_id (str): The id of the Plex user
Optional parameters:
row_ids (str): Comma separated row ids to delete, e.g. "2,3,8"
Returns:
None
Delete and recreate the cache directory.
Delete exports from Tautulli.
Required parameters:
export_id (int): The row id of the exported file to delete
Optional parameters:
delete_all (bool): 'true' to delete all exported files
Returns:
None
Delete history rows from Tautulli.
Required parameters:
row_ids (str): Comma separated row ids to delete, e.g. "65,110,2,3645"
Optional parameters:
None
Returns:
None
Delete the images uploaded to image hosting services.
Required parameters:
None
Optional parameters:
rating_key (int): 1234
(Note: Must be the movie, show, season, artist, or album rating key)
service (str): 'imgur' or 'cloudinary'
delete_all (bool): 'true' to delete all images form the service
Returns:
json:
{"result": "success",
"message": "Deleted hosted images from Imgur."}
Delete and recreate the image cache directory.
Delete a library section from Tautulli. Also erases all history for the library.
Required parameters:
server_id (str): The Plex server identifier of the library section
section_id (str): The id of the Plex library section
Optional parameters:
row_ids (str): Comma separated row ids to delete, e.g. "2,3,8"
Returns:
None
Delete the Tautulli login logs.
Required paramters:
None
Optional parameters:
None
Returns:
None
Delete the 3rd party API lookup info.
Required parameters:
None
Optional parameters:
rating_key (int): 1234
(Note: Must be the movie, show, artist, album, or track rating key)
service (str): 'themoviedb' or 'tvmaze' or 'musicbrainz'
delete_all (bool): 'true' to delete all images form the service
Returns:
json:
{"result": "success",
"message": "Deleted lookup info."}
Delete the media info table cache for a specific library.
Required parameters:
section_id (str): The id of the Plex library section
Optional parameters:
None
Returns:
None
Remove a mobile device from the database.
Required parameters:
mobile_device_id (int): The mobile device database id to delete, OR
device_id (str): The unique device identifier for the mobile device
Optional parameters:
None
Returns:
None
Remove a newsletter from the database.
Required parameters:
newsletter_id (int): The newsletter to delete
Optional parameters:
None
Returns:
None
Delete the Tautulli newsletter logs.
Required paramters:
None
Optional parameters:
None
Returns:
None
Delete the Tautulli notification logs.
Required paramters:
None
Optional parameters:
None
Returns:
None
Remove a notifier from the database.
Required parameters:
notifier_id (int): The notifier to delete
Optional parameters:
None
Returns:
None
Flush out all of the recently added items in the database.
Delete a synced item from a device.
Required parameters:
client_id (str): The client ID of the device to delete from
sync_id (str): The sync ID of the synced item
Optional parameters:
None
Returns:
None
Flush out all of the temporary sessions in the database.
Delete a user from Tautulli. Also erases all history for the user.
Required parameters:
user_id (str): The id of the Plex user
Optional parameters:
row_ids (str): Comma separated row ids to delete, e.g. "2,3,8"
Returns:
None
Return the api docs as a dict where commands are keys, docstring are value.
Return the api docs formatted with markdown.
Download the Tautulli configuration file.
Download the Tautulli database file.
Download an exported metadata file
Required parameters:
export_id (int): The row id of the exported file to download
Optional parameters:
None
Returns:
download
Download the Tautulli log file.
Required parameters:
None
Optional parameters:
logfile (str): The name of the Tautulli log file,
"tautulli", "tautulli_api", "plex_websocket"
Returns:
download
Download the Plex log file.
Required parameters:
None
Optional parameters:
logfile (int): The name of the Plex log file,
e.g. "Plex Media Server", "Plex Media Scanner"
Returns:
download
Update a library section on Tautulli.
Required parameters:
section_id (str): The id of the Plex library section
custom_thumb (str): The URL for the custom library thumbnail
custom_art (str): The URL for the custom library background art
keep_history (int): 0 or 1
Optional parameters:
None
Returns:
None
Update a user on Tautulli.
Required parameters:
user_id (str): The id of the Plex user
friendly_name(str): The friendly name of the user
custom_thumb (str): The URL for the custom user thumbnail
keep_history (int): 0 or 1
allow_guest (int): 0 or 1
Optional paramters:
None
Returns:
None
Export library or media metadata to a file
Required parameters:
section_id (int): The section id of the library items to export, OR
user_id (int): The user id of the playlist items to export, OR
rating_key (int): The rating key of the media item to export
Optional parameters:
file_format (str): csv (default), json, xml, or m3u
metadata_level (int): The level of metadata to export (default 1)
media_info_level (int): The level of media info to export (default 1)
thumb_level (int): The level of poster/cover images to export (default 0)
art_level (int): The level of background artwork images to export (default 0)
custom_fields (str): Comma separated list of custom fields to export
in addition to the export level selected
export_type (str): 'collection' or 'playlist' for library/user export,
otherwise default to all library items
individual_files (bool): Export each item as an individual file for library/user export.
Returns:
json:
{"export_id": 1}
Get the current activity on the PMS.
Required parameters:
None
Optional parameters:
session_key (int): Session key for the session info to return, OR
session_id (str): Session ID for the session info to return
Returns:
json:
{"lan_bandwidth": 25318,
"sessions": [
{
"actors": [
"Kit Harington",
"Emilia Clarke",
"Isaac Hempstead-Wright",
"Maisie Williams",
"Liam Cunningham",
],
"added_at": "1461572396",
"allow_guest": 1,
"art": "/library/metadata/1219/art/1503306930",
"aspect_ratio": "1.78",
"audience_rating": "",
"audience_rating_image": "rottentomatoes://image.rating.upright",
"audio_bitrate": "384",
"audio_bitrate_mode": "",
"audio_channel_layout": "5.1(side)",
"audio_channels": "6",
"audio_codec": "ac3",
"audio_decision": "direct play",
"audio_language": "",
"audio_language_code": "",
"audio_profile": "",
"audio_sample_rate": "48000",
"bandwidth": "25318",
"banner": "/library/metadata/1219/banner/1503306930",
"bif_thumb": "/library/parts/274169/indexes/sd/1000",
"bitrate": "10617",
"channel_call_sign": "",
"channel_identifier": "",
"channel_stream": 0,
"channel_thumb": "",
"children_count": "",
"collections": [],
"container": "mkv",
"container_decision": "direct play",
"content_rating": "TV-MA",
"deleted_user": 0,
"device": "Windows",
"directors": [
"Jeremy Podeswa"
],
"do_notify": 0,
"duration": "2998272",
"email": "Jon.Snow.1337@CastleBlack.com",
"file": "/media/TV Shows/Game of Thrones/Season 06/Game of Thrones - S06E01 - The Red Woman.mkv",
"file_size": "3979115377",
"friendly_name": "Jon Snow",
"full_title": "Game of Thrones - The Red Woman",
"genres": [
"Adventure",
"Drama",
"Fantasy"
],
"grandparent_guid": "com.plexapp.agents.thetvdb://121361?lang=en",
"grandparent_rating_key": "1219",
"grandparent_thumb": "/library/metadata/1219/thumb/1503306930",
"grandparent_title": "Game of Thrones",
"guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en",
"height": "1078",
"id": "",
"indexes": 1,
"ip_address": "10.10.10.1",
"ip_address_public": "64.123.23.111",
"is_admin": 1,
"is_allow_sync": 1,
"is_home_user": 1,
"is_restricted": 0,
"keep_history": 1,
"labels": [],
"last_viewed_at": "1462165717",
"library_name": "TV Shows",
"live": 0,
"live_uuid": "",
"local": "1",
"location": "lan",
"machine_id": "lmd93nkn12k29j2lnm",
"media_index": "1",
"media_type": "episode",
"optimized_version": 0,
"optimized_version_profile": "",
"optimized_version_title": "",
"original_title": "",
"originally_available_at": "2016-04-24",
"parent_guid": "com.plexapp.agents.thetvdb://121361/6?lang=en",
"parent_media_index": "6",
"parent_rating_key": "153036",
"parent_thumb": "/library/metadata/153036/thumb/1503889210",
"parent_title": "Season 6",
"platform": "Plex Media Player",
"platform_name": "plex",
"platform_version": "2.4.1.787-54a020cd",
"player": "Castle-PC",
"product": "Plex Media Player",
"product_version": "3.35.2",
"profile": "Konvergo",
"progress_percent": "0",
"quality_profile": "Original",
"rating": "7.8",
"rating_image": "rottentomatoes://image.rating.ripe",
"rating_key": "153037",
"relay": 0,
"section_id": "2",
"secure": 1,
"session_id": "helf15l3rxgw01xxe0jf3l3d",
"session_key": "27",
"shared_libraries": [
"10",
"1",
"4",
"5",
"15",
"20",
"2"
],
"sort_title": "Red Woman",
"state": "playing",
"stream_aspect_ratio": "1.78",
"stream_audio_bitrate": "384",
"stream_audio_bitrate_mode": "",
"stream_audio_channel_layout": "5.1(side)",
"stream_audio_channel_layout_": "5.1(side)",
"stream_audio_channels": "6",
"stream_audio_codec": "ac3",
"stream_audio_decision": "direct play",
"stream_audio_language": "",
"stream_audio_language_code": "",
"stream_audio_sample_rate": "48000",
"stream_bitrate": "10617",
"stream_container": "mkv",
"stream_container_decision": "direct play",
"stream_duration": "2998272",
"stream_subtitle_codec": "",
"stream_subtitle_container": "",
"stream_subtitle_decision": "",
"stream_subtitle_forced": 0,
"stream_subtitle_format": "",
"stream_subtitle_language": "",
"stream_subtitle_language_code": "",
"stream_subtitle_location": "",
"stream_video_bit_depth": "8",
"stream_video_bitrate": "10233",
"stream_video_chroma_subsampling": "4:2:0",
"stream_video_codec": "h264",
"stream_video_codec_level": "41",
"stream_video_color_primaries": "",
"stream_video_color_range": "tv",
"stream_video_color_space": "bt709",
"stream_video_color_trc": "",
"stream_video_decision": "direct play",
"stream_video_dynamic_range": "SDR",
"stream_video_framerate": "24p",
"stream_video_full_resolution": "1080p",
"stream_video_height": "1078",
"stream_video_language": "",
"stream_video_language_code": "",
"stream_video_ref_frames": "4",
"stream_video_resolution": "1080",
"stream_video_scan_type": "progressive",
"stream_video_width": "1920",
"studio": "HBO",
"subtitle_codec": "",
"subtitle_container": "",
"subtitle_decision": "",
"subtitle_forced": 0,
"subtitle_format": "",
"subtitle_language": "",
"subtitle_language_code": "",
"subtitle_location": "",
"subtitles": 0,
"summary": "Jon Snow is dead. Daenerys meets a strong man. Cersei sees her daughter again.",
"synced_version": 0,
"synced_version_profile": "",
"tagline": "",
"throttled": "0",
"thumb": "/library/metadata/153037/thumb/1503889207",
"title": "The Red Woman",
"transcode_audio_channels": "",
"transcode_audio_codec": "",
"transcode_container": "",
"transcode_decision": "direct play",
"transcode_height": "",
"transcode_hw_decode": "",
"transcode_hw_decode_title": "",
"transcode_hw_decoding": 0,
"transcode_hw_encode": "",
"transcode_hw_encode_title": "",
"transcode_hw_encoding": 0,
"transcode_hw_full_pipeline": 0,
"transcode_hw_requested": 0,
"transcode_key": "",
"transcode_max_offset_available": 0,
"transcode_min_offset_available": 0,
"transcode_progress": 0,
"transcode_protocol": "",
"transcode_speed": "",
"transcode_throttled": 0,
"transcode_video_codec": "",
"transcode_width": "",
"type": "",
"updated_at": "1503889207",
"user": "LordCommanderSnow",
"user_id": 133788,
"user_rating": "",
"user_thumb": "https://plex.tv/users/k10w42309cynaopq/avatar",
"username": "LordCommanderSnow",
"video_bit_depth": "8",
"video_bitrate": "10233",
"video_chroma_subsampling": "4:2:0",
"video_codec": "h264",
"video_codec_level": "41",
"video_color_primaries": "",
"video_color_range": "tv",
"video_color_space": "bt709",
"video_color_trc": ",
"video_decision": "direct play",
"video_dynamic_range": "SDR",
"video_frame_rate": "23.976",
"video_framerate": "24p",
"video_full_resolution": "1080p",
"video_height": "1078",
"video_language": "",
"video_language_code": "",
"video_profile": "high",
"video_ref_frames": "4",
"video_resolution": "1080",
"video_scan_type": "progressive",
"video_width": "1920",
"view_offset": "1000",
"width": "1920",
"writers": [
"David Benioff",
"D. B. Weiss"
],
"year": "2016"
}
],
"stream_count": "1",
"stream_count_direct_play": 1,
"stream_count_direct_stream": 0,
"stream_count_transcode": 0,
"total_bandwidth": 25318,
"wan_bandwidth": 0
}
Get the apikey. Username and password are required if auth is enabled. Makes and saves the apikey if it does not exist.
Required parameters:
None
Optional parameters:
username (str): Your Tautulli username
password (str): Your Tautulli password
Returns:
string: "apikey"
Get the metadata for the children of a media item.
Required parameters:
rating_key (str): Rating key of the item
media_type (str): Media type of the item
Optional parameters:
None
Returns:
json:
{"children_count": 9,
"children_type": "season",
"title": "Game of Thrones",
"children_list": [
{...},
{"actors": [],
"added_at": "1403553078",
"art": "/library/metadata/1219/art/1562110346",
"audience_rating": "",
"audience_rating_image": "",
"banner": "",
"collections": [],
"content_rating": "",
"directors": [],
"duration": "",
"full_title": "Season 1"
"genres": [],
"grandparent_rating_key": "",
"grandparent_thumb": "",
"grandparent_title": "",
"guid": "com.plexapp.agents.thetvdb://121361/1?lang=en",
"labels": [],
"last_viewed_at": "1589992348",
"library_name": "TV Shows",
"media_index": "1",
"media_type": "season",
"original_title": "",
"originally_available_at": "",
"parent_media_index": "1",
"parent_rating_key": "1219",
"parent_thumb": "/library/metadata/1219/thumb/1562110346",
"parent_title": "Game of Thrones",
"rating": "",
"rating_image": "",
"rating_key": "1220",
"section_id": "2",
"sort_title": "",
"studio": "",
"summary": "",
"tagline": "",
"thumb": "/library/metadata/1220/thumb/1602176313",
"title": "Season 1",
"updated_at": "1602176313",
"user_rating": "",
"writers": [],
"year": ""
},
{...},
{...}
]
}
Get the data on the Tautulli collections tables.
Required parameters:
section_id (str): The id of the Plex library section
Optional parameters:
None
Returns:
json:
{"draw": 1,
"recordsTotal": 5,
"data":
[...]
}
Get the date and time formats used by Tautulli.
Required parameters:
None
Optional parameters:
None
Returns:
json:
{"date_format": "YYYY-MM-DD",
"time_format": "HH:mm",
}
Get a list of available custom export fields.
Required parameters:
media_type (str): The media type of the fields to return
Optional parameters:
sub_media_type (str): The child media type for
collections (movie, show, artist, album, photoalbum),
or playlists (video, audio, photo)
Returns:
json:
{"metadata_fields":
[{"field": "addedAt", "level": 1},
...
],
"media_info_fields":
[{"field": "media.aspectRatio", "level": 1},
...
]
}
Get the data on the Tautulli export tables.
Required parameters:
section_id (str): The id of the Plex library section, OR
user_id (str): The id of the Plex user, OR
rating_key (str): The rating key of the exported item
Optional parameters:
order_column (str): "added_at", "sort_title", "container", "bitrate", "video_codec",
"video_resolution", "video_framerate", "audio_codec", "audio_channels",
"file_size", "last_played", "play_count"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "Thrones"
Returns:
json:
{"draw": 1,
"recordsTotal": 10,
"recordsFiltered": 3,
"data":
[{"timestamp": 1602823644,
"art_level": 0,
"complete": 1,
"custom_fields": "",
"exists": true,
"export_id": 42,
"exported_items": 28,
"file_format": "json",
"file_size": 57793562,
"filename": null,
"individual_files": 1,
"media_info_level": 1,
"media_type": "collection",
"media_type_title": "Collection",
"metadata_level": 1,
"rating_key": null,
"section_id": 1,
"thumb_level": 2,
"title": "Library - Movies - Collection [1]",
"total_items": 28,
"user_id": null
},
{...},
{...}
]
}
Get the geolocation info for an IP address.
Required parameters:
ip_address
Optional parameters:
None
Returns:
json:
{"city": "Mountain View",
"code": "US",
"continent": "NA",
"country": "United States",
"latitude": 37.386,
"longitude": -122.0838,
"postal_code": "94035",
"region": "California",
"timezone": "America/Los_Angeles",
"accuracy": null
}
Get the Tautulli history.
Required parameters:
None
Optional parameters:
grouping (int): 0 or 1
include_activity (int): 0 or 1
user (str): "Jon Snow"
user_id (int): 133788
rating_key (int): 4348
parent_rating_key (int): 544
grandparent_rating_key (int): 351
start_date (str): History for the exact date, "YYYY-MM-DD"
before (str): History before and including the date, "YYYY-MM-DD"
after (str): History after and including the date, "YYYY-MM-DD"
section_id (int): 2
media_type (str): "movie", "episode", "track", "live", "collection", "playlist"
transcode_decision (str): "direct play", "copy", "transcode",
guid (str): Plex guid for an item, e.g. "com.plexapp.agents.thetvdb://121361/6/1"
order_column (str): "date", "friendly_name", "ip_address", "platform", "player",
"full_title", "started", "paused_counter", "stopped", "duration"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "Thrones"
Returns:
json:
{"draw": 1,
"recordsTotal": 1000,
"recordsFiltered": 250,
"total_duration": "42 days 5 hrs 18 mins",
"filter_duration": "10 hrs 12 mins",
"data":
[{"date": 1462687607,
"friendly_name": "Mother of Dragons",
"full_title": "Game of Thrones - The Red Woman",
"grandparent_rating_key": 351,
"grandparent_title": "Game of Thrones",
"original_title": "",
"group_count": 1,
"group_ids": "1124",
"guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en",
"ip_address": "xxx.xxx.xxx.xxx",
"live": 0,
"location": "wan",
"machine_id": "lmd93nkn12k29j2lnm",
"media_index": 17,
"media_type": "episode",
"originally_available_at": "2016-04-24",
"parent_media_index": 7,
"parent_rating_key": 544,
"parent_title": "",
"paused_counter": 0,
"percent_complete": 84,
"platform": "Windows",
"play_duration": 263,
"product": "Plex for Windows",
"player": "Castle-PC",
"rating_key": 4348,
"reference_id": 1123,
"relayed": 0,
"row_id": 1124,
"secure": 1,
"session_key": null,
"started": 1462688107,
"state": null,
"stopped": 1462688370,
"thumb": "/library/metadata/4348/thumb/1462414561",
"title": "The Red Woman",
"transcode_decision": "transcode",
"user": "DanyKhaleesi69",
"user_id": 8008135,
"watched_status": 0,
"year": 2016
},
{...},
{...}
]
}
Get the homepage watch statistics.
Required parameters:
None
Optional parameters:
grouping (int): 0 or 1
time_range (int): The time range to calculate statistics, 30
stats_type (str): 'plays' or 'duration'
stats_start (int) The row number of the stat item to start at, 0
stats_count (int): The number of stat items to return, 5
stat_id (str): A single stat to return, 'top_movies', 'popular_movies',
'top_tv', 'popular_tv', 'top_music', 'popular_music', 'top_libraries',
'top_users', 'top_platforms', 'last_watched', 'most_concurrent'
section_id (int): The id of the Plex library section
user_id (int): The id of the Plex user
Returns:
json:
[{"stat_id": "top_movies",
"stat_type": "total_plays",
"rows": [{...}]
},
{"stat_id": "popular_movies",
"rows": [{...}]
},
{"stat_id": "top_tv",
"stat_type": "total_plays",
"rows":
[{"content_rating": "TV-MA",
"friendly_name": "",
"grandparent_thumb": "/library/metadata/1219/thumb/1462175063",
"guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en",
"labels": [],
"last_play": 1462380698,
"live": 0,
"media_type": "episode",
"platform": "",
"rating_key": 1219,
"row_id": 1116,
"section_id": 2,
"thumb": "",
"title": "Game of Thrones",
"total_duration": 213302,
"total_plays": 69,
"user": "",
"users_watched": ""
},
{...},
{...}
]
},
{"stat_id": "popular_tv",
"rows": [{...}]
},
{"stat_id": "top_music",
"stat_type": "total_plays",
"rows": [{...}]
},
{"stat_id": "popular_music",
"rows": [{...}]
},
{"stat_id": "last_watched",
"rows": [{...}]
},
{"stat_id": "top_libraries",
"stat_type": "total_plays",
"rows": [{...}]
},
{"stat_id": "top_users",
"stat_type": "total_plays",
"rows": [{...}]
},
{"stat_id": "top_platforms",
"stat_type": "total_plays",
"rows": [{...}]
},
{"stat_id": "most_concurrent",
"rows": [{...}]
}
]
Get the user stats for the media item.
Required parameters:
rating_key (str): Rating key of the item
Optional parameters:
media_type (str): Media type of the item (only required for a collection)
grouping (int): 0 or 1
Returns:
json:
[
{
"friendly_name": "Jon Snow",
"user_id": 1601089,
"user_thumb": "",
"username": "jsnow@thewinteriscoming.com",
"total_plays": 6,
"total_time": 28743
},
{
"friendly_name": "DanyKhaleesi69",
"user_id": 8008135,
"user_thumb": "",
"username": "DanyKhaleesi69",
"total_plays": 5,
"total_time": 18583
}
]
Get the watch time stats for the media item.
Required parameters:
rating_key (str): Rating key of the item
Optional parameters:
media_type (str): Media type of the item (only required for a collection)
grouping (int): 0 or 1
query_days (str): Comma separated days, e.g. "1,7,30,0"
Returns:
json:
[
{
"query_days": 1,
"total_time": 0,
"total_plays": 0
},
{
"query_days": 7,
"total_time": 0,
"total_plays": 0
},
{
"query_days": 30,
"total_time": 0,
"total_plays": 0
},
{
"query_days": 0,
"total_time": 57776,
"total_plays": 13
}
]
Get a list of all libraries on your server.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"art": "/:/resources/show-fanart.jpg",
"child_count": "3745",
"count": "62",
"is_active": 1,
"parent_count": "240",
"section_id": "2",
"section_name": "TV Shows",
"section_type": "show",
"thumb": "/:/resources/show.png"
},
{...},
{...}
]
Get the data on the Tautulli libraries table.
Required parameters:
None
Optional parameters:
grouping (int): 0 or 1
order_column (str): "library_thumb", "section_name", "section_type", "count", "parent_count",
"child_count", "last_accessed", "last_played", "plays", "duration"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "Movies"
Returns:
json:
{"draw": 1,
"recordsTotal": 10,
"recordsFiltered": 10,
"data":
[{"child_count": 3745,
"content_rating": "TV-MA",
"count": 62,
"do_notify": 1,
"do_notify_created": 1,
"duration": 1578037,
"guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en",
"histroy_row_id": 1128,
"is_active": 1,
"keep_history": 1,
"labels": [],
"last_accessed": 1462693216,
"last_played": "Game of Thrones - The Red Woman",
"library_art": "/:/resources/show-fanart.jpg",
"library_thumb": "/:/resources/show.png",
"live": 0,
"media_index": 1,
"media_type": "episode",
"originally_available_at": "2016-04-24",
"parent_count": 240,
"parent_media_index": 6,
"parent_title": "",
"plays": 772,
"rating_key": 153037,
"row_id": 1,
"section_id": 2,
"section_name": "TV Shows",
"section_type": "Show",
"server_id": "ds48g4r354a8v9byrrtr697g3g79w",
"thumb": "/library/metadata/153036/thumb/1462175062",
"year": 2016
},
{...},
{...}
]
}
Get a library's details.
Required parameters:
section_id (str): The id of the Plex library section
Optional parameters:
include_last_accessed (bool): True to include the last_accessed value for the library.
Returns:
json:
{"child_count": null,
"count": 887,
"deleted_section": 0,
"do_notify": 1,
"do_notify_created": 1,
"is_active": 1,
"keep_history": 1,
"last_accessed": 1462693216,
"library_art": "/:/resources/movie-fanart.jpg",
"library_thumb": "/:/resources/movie.png",
"parent_count": null,
"row_id": 1,
"section_id": 1,
"section_name": "Movies",
"section_type": "movie",
"server_id": "ds48g4r354a8v9byrrtr697g3g79w"
}
Get the data on the Tautulli media info tables.
Required parameters:
section_id (str): The id of the Plex library section, OR
rating_key (str): The grandparent or parent rating key
Optional parameters:
section_type (str): "movie", "show", "artist", "photo"
order_column (str): "added_at", "sort_title", "container", "bitrate", "video_codec",
"video_resolution", "video_framerate", "audio_codec", "audio_channels",
"file_size", "last_played", "play_count"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "Thrones"
refresh (str): "true" to refresh the media info table
Returns:
json:
{"draw": 1,
"last_refreshed": 1678734670,
"recordsTotal": 82,
"recordsFiltered": 82,
"filtered_file_size": 2616760056742,
"total_file_size": 2616760056742,
"data":
[{"added_at": "1403553078",
"audio_channels": "",
"audio_codec": "",
"bitrate": "",
"container": "",
"file_size": 253660175293,
"grandparent_rating_key": "",
"last_played": 1462380698,
"media_index": "1",
"media_type": "show",
"parent_media_index": "",
"parent_rating_key": "",
"play_count": 15,
"rating_key": "1219",
"section_id": 2,
"section_type": "show",
"sort_title": "Game of Thrones",
"thumb": "/library/metadata/1219/thumb/1436265995",
"title": "Game of Thrones",
"video_codec": "",
"video_framerate": "",
"video_resolution": "",
"year": "2011"
},
{...},
{...}
]
}
Get a list of library sections and ids on the PMS.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"section_id": 1, "section_name": "Movies", "section_type": "movie"},
{"section_id": 7, "section_name": "Music", "section_type": "artist"},
{"section_id": 2, "section_name": "TV Shows", "section_type": "show"},
{...}
]
Get a library's user statistics.
Required parameters:
section_id (str): The id of the Plex library section
Optional parameters:
grouping (int): 0 or 1
Returns:
json:
[{"friendly_name": "Jon Snow",
"total_plays": 170,
"total_time": 349618,
"user_id": 133788,
"user_thumb": "https://plex.tv/users/k10w42309cynaopq/avatar",
"username": "LordCommanderSnow"
},
{"friendly_name": "DanyKhaleesi69",
"total_plays": 42,
"total_time": 50185,
"user_id": 8008135,
"user_thumb": "https://plex.tv/users/568gwwoib5t98a3a/avatar",
"username: "DanyKhaleesi69"
},
{...},
{...}
]
Get a library's watch time statistics.
Required parameters:
section_id (str): The id of the Plex library section
Optional parameters:
grouping (int): 0 or 1
query_days (str): Comma separated days, e.g. "1,7,30,0"
Returns:
json:
[{"query_days": 1,
"total_plays": 0,
"total_time": 0
},
{"query_days": 7,
"total_plays": 3,
"total_time": 15694
},
{"query_days": 30,
"total_plays": 35,
"total_time": 63054
},
{"query_days": 0,
"total_plays": 508,
"total_time": 1183080
}
]
Get the Tautulli logs.
Required parameters:
None
Optional parameters:
sort (str): "time", "thread", "msg", "loglevel"
search (str): A string to search for
order (str): "desc" or "asc"
regex (str): A regex string to search for
start (int): Row number to start from
end (int): Row number to end at
Returns:
json:
[{"loglevel": "DEBUG",
"msg": "Latest version is 2d10b0748c7fa2ee4cf59960c3d3fffc6aa9512b",
"thread": "MainThread",
"time": "2016-05-08 09:36:51 "
},
{...},
{...}
]
Get the metadata for a media item.
Required parameters:
rating_key (str): Rating key of the item, OR
sync_id (str): Sync ID of a synced item
Optional parameters:
None
Returns:
json:
{"actors": [
"Emilia Clarke",
"Lena Headey",
"Sophie Turner",
"Kit Harington",
"Peter Dinklage",
"Nikolaj Coster-Waldau",
"Maisie Williams",
"Iain Glen",
"John Bradley",
"Alfie Allen"
],
"added_at": "1461572396",
"art": "/library/metadata/1219/art/1462175063",
"audience_rating": "7.4",
"audience_rating_image": "themoviedb://image.rating",
"banner": "/library/metadata/1219/banner/1462175063",
"collections": [],
"content_rating": "TV-MA",
"directors": [
"Jeremy Podeswa"
],
"duration": "2998290",
"edition_title": "",
"full_title": "Game of Thrones - The Red Woman",
"genres": [
"Action/Adventure",
"Drama",
"Fantasy",
"Romance"
],
"grandparent_guid": "plex://show/5d9c086c46115600200aa2fe",
"grandparent_guids": [
"imdb://tt0944947",
"tmdb://1399",
"tvdb://121361"
],
"grandparent_rating_key": "1219",
"grandparent_thumb": "/library/metadata/1219/thumb/1462175063",
"grandparent_title": "Game of Thrones",
"grandparent_year": "2011",
"guid": "plex://episode/5d9c1276e9d5a1001f4ff2fa",
"guids": [
"imdb://tt3658014",
"tmdb://1156503",
"tvdb://5469015"
],
"labels": [],
"last_viewed_at": "1462165717",
"library_name": "TV Shows",
"live": 0,
"markers": [
{
"id": 908,
"type": "credits",
"start_time_offset": 2923863,
"end_time_offset": 2998197,
"first": true,
"final": true
},
{
"id": 908,
"type": "intro",
"start_time_offset": 1622,
"end_time_offset": 109135,
"first": null,
"final": null
}
],
"media_index": "1",
"media_info": [
{
"aspect_ratio": "1.78",
"audio_channel_layout": "5.1",
"audio_channels": "6",
"audio_codec": "ac3",
"audio_profile": "",
"bitrate": "10617",
"channel_call_sign": "",
"channel_identifier": "",
"channel_thumb": "",
"container": "mkv",
"height": "1078",
"id": "257925",
"optimized_version": 0,
"parts": [
{
"file": "/media/TV Shows/Game of Thrones/Season 06/Game of Thrones - S06E01 - The Red Woman.mkv",
"file_size": "3979115377",
"id": "274169",
"indexes": 1,
"streams": [
{
"id": "511663",
"type": "1",
"video_bit_depth": "8",
"video_bitrate": "10233",
"video_codec": "h264",
"video_codec_level": "41",
"video_color_primaries": "",
"video_color_range": "tv",
"video_color_space": "bt709",
"video_color_trc": "",
"video_dynamic_range": "SDR",
"video_frame_rate": "23.976",
"video_height": "1078",
"video_language": "",
"video_language_code": "",
"video_profile": "high",
"video_ref_frames": "4",
"video_scan_type": "progressive",
"video_width": "1920",
"selected": 0
},
{
"audio_bitrate": "384",
"audio_bitrate_mode": "",
"audio_channel_layout": "5.1(side)",
"audio_channels": "6",
"audio_codec": "ac3",
"audio_language": "",
"audio_language_code": "",
"audio_profile": "",
"audio_sample_rate": "48000",
"id": "511664",
"type": "2",
"selected": 1
},
{
"id": "511953",
"subtitle_codec": "srt",
"subtitle_container": "",
"subtitle_forced": 0,
"subtitle_format": "srt",
"subtitle_language": "English",
"subtitle_language_code": "eng",
"subtitle_location": "external",
"type": "3",
"selected": 1
}
]
}
],
"video_codec": "h264",
"video_framerate": "24p",
"video_full_resolution": "1080p",
"video_profile": "high",
"video_resolution": "1080",
"width": "1920"
}
],
"media_type": "episode",
"original_title": "",
"originally_available_at": "2016-04-24",
"parent_guid": "plex://season/602e67e61d3358002c4120f7",
"parent_guids": [
"tvdb://651357"
],
"parent_media_index": "6",
"parent_rating_key": "153036",
"parent_thumb": "/library/metadata/153036/thumb/1462175062",
"parent_title": "Season 6",
"parent_year": "2016",
"rating": "",
"rating_image": "",
"rating_key": "153037",
"section_id": "2",
"sort_title": "Red Woman",
"studio": "Revolution Sun Studios",
"summary": "The fate of Jon Snow is revealed. Daenerys meets a strong man. Cersei sees her daughter once again.",
"tagline": "",
"thumb": "/library/metadata/153037/thumb/1462175060",
"title": "The Red Woman",
"updated_at": "1462175060",
"user_rating": "9.0",
"writers": [
"David Benioff",
"D. B. Weiss"
],
"year": "2016"
}
Get a list of new rating keys for the PMS of all of the item's parent/children.
Required parameters:
rating_key (str): '12345'
media_type (str): "movie", "show", "season", "episode", "artist", "album", "track"
Optional parameters:
None
Returns:
json:
{}
Get the configuration for an existing notification agent.
Required parameters:
newsletter_id (int): The newsletter config to retrieve
Optional parameters:
None
Returns:
json:
{"id": 1,
"agent_id": 0,
"agent_name": "recently_added",
"agent_label": "Recently Added",
"friendly_name": "",
"id_name": "",
"cron": "0 0 * * 1",
"active": 1,
"subject": "Recently Added to {server_name}! ({end_date})",
"body": "View the newsletter here: {newsletter_url}",
"message": "",
"config": {"custom_cron": 0,
"filename": "newsletter_{newsletter_uuid}.html",
"formatted": 1,
"incl_libraries": ["1", "2"],
"notifier_id": 1,
"save_only": 0,
"time_frame": 7,
"time_frame_units": "days"
},
"email_config": {...},
"config_options": [{...}, ...],
"email_config_options": [{...}, ...]
}
Get the data on the Tautulli newsletter logs table.
Required parameters:
None
Optional parameters:
order_column (str): "timestamp", "newsletter_id", "agent_name", "notify_action",
"subject_text", "start_date", "end_date", "uuid"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "Telegram"
Returns:
json:
{"draw": 1,
"recordsTotal": 1039,
"recordsFiltered": 163,
"data":
[{"agent_id": 0,
"agent_name": "recently_added",
"end_date": "2018-03-18",
"id": 7,
"newsletter_id": 1,
"notify_action": "on_cron",
"start_date": "2018-03-05",
"subject_text": "Recently Added to Plex (Winterfell-Server)! (2018-03-18)",
"success": 1,
"timestamp": 1462253821,
"uuid": "7fe4g65i"
},
{...},
{...}
]
}
Get a list of configured newsletters.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"id": 1,
"agent_id": 0,
"agent_name": "recently_added",
"agent_label": "Recently Added",
"friendly_name": "",
"cron": "0 0 * * 1",
"active": 1
}
]
Get the data on the Tautulli notification logs table.
Required parameters:
None
Optional parameters:
order_column (str): "timestamp", "notifier_id", "agent_name", "notify_action",
"subject_text", "body_text",
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "Telegram"
Returns:
json:
{"draw": 1,
"recordsTotal": 1039,
"recordsFiltered": 163,
"data":
[{"agent_id": 13,
"agent_name": "telegram",
"body_text": "DanyKhaleesi69 started playing The Red Woman.",
"id": 1000,
"notify_action": "on_play",
"rating_key": 153037,
"session_key": 147,
"subject_text": "Tautulli (Winterfell-Server)",
"success": 1,
"timestamp": 1462253821,
"user": "DanyKhaleesi69",
"user_id": 8008135
},
{...},
{...}
]
}
Get the configuration for an existing notification agent.
Required parameters:
notifier_id (int): The notifier config to retrieve
Optional parameters:
None
Returns:
json:
{"id": 1,
"agent_id": 13,
"agent_name": "telegram",
"agent_label": "Telegram",
"friendly_name": "",
"config": {"incl_poster": 0,
"html_support": 1,
"chat_id": "123456",
"bot_token": "13456789:fio9040NNo04jLEp-4S",
"incl_subject": 1,
"disable_web_preview": 0
},
"config_options": [{...}, ...]
"actions": {"on_play": 0,
"on_stop": 0,
...
},
"notify_text": {"on_play": {"subject": "...",
"body": "..."
}
"on_stop": {"subject": "...",
"body": "..."
}
...
}
}
Get the list of available notification parameters.
Required parameters:
None
Optional parameters:
None
Returns:
json:
{
}
Get a list of configured notifiers.
Required parameters:
None
Optional parameters:
notify_action (str): The notification action to filter out
Returns:
json:
[{"id": 1,
"agent_id": 13,
"agent_name": "telegram",
"agent_label": "Telegram",
"friendly_name": "",
"active": 1
}
]
Get a list of old rating keys from the Tautulli database for all of the item's parent/children.
Required parameters:
rating_key (str): '12345'
media_type (str): "movie", "show", "season", "episode", "artist", "album", "track"
Optional parameters:
None
Returns:
json:
{}
Get the data on the Tautulli playlists tables.
Required parameters:
section_id (str): The section id of the Plex library, OR
user_id (str): The user id of the Plex user
Optional parameters:
None
Returns:
json:
{"draw": 1,
"recordsTotal": 5,
"data":
[...]
}
Get graph data by date.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["YYYY-MM-DD", "YYYY-MM-DD", ...]
"series":
[{"name": "Movies", "data": [...]}
{"name": "TV", "data": [...]},
{"name": "Music", "data": [...]},
{"name": "Live TV", "data": [...]}
]
}
Get graph data by day of the week.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["Sunday", "Monday", "Tuesday", ..., "Saturday"]
"series":
[{"name": "Movies", "data": [...]}
{"name": "TV", "data": [...]},
{"name": "Music", "data": [...]},
{"name": "Live TV", "data": [...]}
]
}
Get graph data by hour of the day.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["00", "01", "02", ..., "23"]
"series":
[{"name": "Movies", "data": [...]}
{"name": "TV", "data": [...]},
{"name": "Music", "data": [...]},
{"name": "Live TV", "data": [...]}
]
}
Get graph data by source resolution.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["720", "1080", "sd", ...]
"series":
[{"name": "Direct Play", "data": [...]}
{"name": "Direct Stream", "data": [...]},
{"name": "Transcode", "data": [...]}
]
}
Get graph data by stream resolution.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["720", "1080", "sd", ...]
"series":
[{"name": "Direct Play", "data": [...]}
{"name": "Direct Stream", "data": [...]},
{"name": "Transcode", "data": [...]}
]
}
Get graph data by stream type by date.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["YYYY-MM-DD", "YYYY-MM-DD", ...]
"series":
[{"name": "Direct Play", "data": [...]}
{"name": "Direct Stream", "data": [...]},
{"name": "Transcode", "data": [...]}
]
}
Get graph data by top 10 platforms.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["iOS", "Android", "Chrome", ...]
"series":
[{"name": "Movies", "data": [...]}
{"name": "TV", "data": [...]},
{"name": "Music", "data": [...]},
{"name": "Live TV", "data": [...]}
]
}
Get graph data by top 10 users.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["Jon Snow", "DanyKhaleesi69", "A Girl", ...]
"series":
[{"name": "Movies", "data": [...]}
{"name": "TV", "data": [...]},
{"name": "Music", "data": [...]},
{"name": "Live TV", "data": [...]}
]
}
Get graph data by month.
Required parameters:
None
Optional parameters:
time_range (str): The number of months of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["Jan 2016", "Feb 2016", "Mar 2016", ...]
"series":
[{"name": "Movies", "data": [...]}
{"name": "TV", "data": [...]},
{"name": "Music", "data": [...]},
{"name": "Live TV", "data": [...]}
]
}
Get the PMS logs.
Required parameters:
None
Optional parameters:
window (int): The number of tail lines to return
logfile (int): The name of the Plex log file,
e.g. "Plex Media Server", "Plex Media Scanner"
Returns:
json:
[["May 08, 2016 09:35:37",
"DEBUG",
"Auth: Came in with a super-token, authorization succeeded."
],
[...],
[...]
]
Check for updates to the Plex Media Server.
Required parameters:
None
Optional parameters:
None
Returns:
json:
{"update_available": true,
"platform": "Windows",
"release_date": "1473721409",
"version": "1.1.4.2757-24ffd60",
"requirements": "...",
"extra_info": "...",
"changelog_added": "...",
"changelog_fixed": "...",
"label": "Download",
"distro": "english",
"distro_build": "windows-i386",
"download_url": "https://downloads.plex.tv/...",
}
Get all items that where recently added to plex.
Required parameters:
count (str): Number of items to return
Optional parameters:
start (str): The item number to start at
media_type (str): The media type: movie, show, artist
section_id (str): The id of the Plex library section
Returns:
json:
{"recently_added":
[{"actors": [
"Kit Harington",
"Emilia Clarke",
"Isaac Hempstead-Wright",
"Maisie Williams",
"Liam Cunningham",
],
"added_at": "1461572396",
"art": "/library/metadata/1219/art/1462175063",
"audience_rating": "8",
"audience_rating_image": "rottentomatoes://image.rating.upright",
"banner": "/library/metadata/1219/banner/1462175063",
"directors": [
"Jeremy Podeswa"
],
"duration": "2998290",
"full_title": "Game of Thrones - The Red Woman",
"genres": [
"Adventure",
"Drama",
"Fantasy"
],
"grandparent_rating_key": "1219",
"grandparent_thumb": "/library/metadata/1219/thumb/1462175063",
"grandparent_title": "Game of Thrones",
"guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en",
"guids": [],
"labels": [],
"last_viewed_at": "1462165717",
"library_name": "TV Shows",
"media_index": "1",
"media_type": "episode",
"original_title": "",
"originally_available_at": "2016-04-24",
"parent_media_index": "6",
"parent_rating_key": "153036",
"parent_thumb": "/library/metadata/153036/thumb/1462175062",
"parent_title": "",
"rating": "7.8",
"rating_image": "rottentomatoes://image.rating.ripe",
"rating_key": "153037",
"section_id": "2",
"sort_title": "Red Woman",
"studio": "HBO",
"summary": "Jon Snow is dead. Daenerys meets a strong man. Cersei sees her daughter again.",
"tagline": "",
"thumb": "/library/metadata/153037/thumb/1462175060",
"title": "The Red Woman",
"user_rating": "9.0",
"updated_at": "1462175060",
"writers": [
"David Benioff",
"D. B. Weiss"
],
"year": "2016"
},
{...},
{...}
]
}
Get the name of the PMS.
Required parameters:
None
Optional parameters:
None
Returns:
string: "Winterfell-Server"
Get the PMS server identifier.
Required parameters:
hostname (str): 'localhost' or '192.160.0.10'
port (int): 32400
Optional parameters:
ssl (int): 0 or 1
remote (int): 0 or 1
Returns:
json:
{'identifier': '08u2phnlkdshf890bhdlksghnljsahgleikjfg9t'}
Get info about the local server.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"machine_identifier": "ds48g4r354a8v9byrrtr697g3g79w",
"version": "0.9.15.x.xxx-xxxxxxx"
}
]
Get the PMS server information.
Required parameters:
None
Optional parameters:
None
Returns:
json:
{"pms_identifier": "08u2phnlkdshf890bhdlksghnljsahgleikjfg9t",
"pms_ip": "10.10.10.1",
"pms_is_remote": 0,
"pms_name": "Winterfell-Server",
"pms_platform": "Windows",
"pms_plexpass": 1,
"pms_port": 32400,
"pms_ssl": 0,
"pms_url": "http://10.10.10.1:32400",
"pms_url_manual": 0,
"pms_version": "1.20.0.3133-fede5bdc7"
}
Get all your servers that are published to Plex.tv.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"clientIdentifier": "ds48g4r354a8v9byrrtr697g3g79w",
"httpsRequired": "0",
"ip": "xxx.xxx.xxx.xxx",
"label": "Winterfell-Server",
"local": "1",
"port": "32400",
"value": "xxx.xxx.xxx.xxx"
},
{...},
{...}
]
Get a specified PMS server preference.
Required parameters:
pref (str): Name of preference
Returns:
string: Value of preference
Get info about the PMS.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"port": "32400",
"host": "10.0.0.97",
"version": "0.9.15.2.1663-7efd046",
"name": "Winterfell-Server",
"machine_identifier": "ds48g4r354a8v9byrrtr697g3g79w"
}
]
Gets all settings from the config file.
Required parameters:
None
Optional parameters:
key (str): Name of a config section to return
Returns:
json:
{"General": {"api_enabled": true, ...}
"Advanced": {"cache_sizemb": "32", ...},
...
}
Get the stream details from history or current stream.
Required parameters:
row_id (int): The row ID number for the history item, OR
session_key (int): The session key of the current stream
Optional parameters:
None
Returns:
json:
{"aspect_ratio": "2.35",
"audio_bitrate": 231,
"audio_channels": 6,
"audio_language": "English",
"audio_language_code": "eng",
"audio_codec": "aac",
"audio_decision": "transcode",
"bitrate": 2731,
"container": "mp4",
"current_session": "",
"grandparent_title": "",
"media_type": "movie",
"optimized_version": "",
"optimized_version_profile": "",
"optimized_version_title": "",
"original_title": "",
"pre_tautulli": "",
"quality_profile": "1.5 Mbps 480p",
"stream_audio_bitrate": 203,
"stream_audio_channels": 2,
"stream_audio_language": "English",
"stream_audio_language_code", "eng",
"stream_audio_codec": "aac",
"stream_audio_decision": "transcode",
"stream_bitrate": 730,
"stream_container": "mkv",
"stream_container_decision": "transcode",
"stream_subtitle_codec": "",
"stream_subtitle_decision": "",
"stream_video_bitrate": 527,
"stream_video_codec": "h264",
"stream_video_decision": "transcode",
"stream_video_dynamic_range": "SDR",
"stream_video_framerate": "24p",
"stream_video_height": 306,
"stream_video_resolution": "SD",
"stream_video_width": 720,
"subtitle_codec": "",
"subtitles": "",
"synced_version": "",
"synced_version_profile": "",
"title": "Frozen",
"transcode_hw_decoding": "",
"transcode_hw_encoding": "",
"video_bitrate": 2500,
"video_codec": "h264",
"video_decision": "transcode",
"video_dynamic_range": "SDR",
"video_framerate": "24p",
"video_height": 816,
"video_resolution": "1080",
"video_width": 1920
}
Get graph data by stream type by top 10 platforms.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["iOS", "Android", "Chrome", ...]
"series":
[{"name": "Direct Play", "data": [...]}
{"name": "Direct Stream", "data": [...]},
{"name": "Transcode", "data": [...]}
]
}
Get graph data by stream type by top 10 users.
Required parameters:
None
Optional parameters:
time_range (str): The number of days of data to return
y_axis (str): "plays" or "duration"
user_id (str): Comma separated list of user id to filter the data
grouping (int): 0 or 1
Returns:
json:
{"categories":
["Jon Snow", "DanyKhaleesi69", "A Girl", ...]
"series":
[{"name": "Direct Play", "data": [...]}
{"name": "Direct Stream", "data": [...]},
{"name": "Transcode", "data": [...]}
]
}
Get a list of synced items on the PMS.
Required parameters:
None
Optional parameters:
machine_id (str): The PMS identifier
user_id (str): The id of the Plex user
Returns:
json:
[{"audio_bitrate": "192",
"client_id": "95434se643fsf24f-com-plexapp-android",
"content_type": "video",
"device_name": "Tyrion's iPad",
"failure": "",
"item_complete_count": "1",
"item_count": "1",
"item_downloaded_count": "1",
"item_downloaded_percent_complete": 100,
"metadata_type": "movie",
"photo_quality": "74",
"platform": "iOS",
"rating_key": "154092",
"root_title": "Movies",
"state": "complete",
"sync_id": "11617019",
"sync_media_type": null,
"sync_title": "Deadpool",
"total_size": "560718134",
"user": "DrukenDwarfMan",
"user_id": "696969",
"username": "DrukenDwarfMan",
"video_bitrate": "4000"
"video_quality": "100"
},
{...},
{...}
]
Get info about the Tautulli server.
Required parameters:
None
Optional parameters:
None
Returns:
json:
{"tautulli_install_type": "git",
"tautulli_version": "v2.8.1",
"tautulli_branch": "master",
"tautulli_commit": "2410eb33805aaac4bd1c5dad0f71e4f15afaf742",
"tautulli_platform": "Windows",
"tautulli_platform_release": "10",
"tautulli_platform_version": "10.0.19043",
"tautulli_platform_linux_distro": "",
"tautulli_platform_device_name": "Winterfell-Server",
"tautulli_python_version": "3.10.0"
}
Get a user's details.
Required parameters:
user_id (str): The id of the Plex user
Optional parameters:
include_last_seen (bool): True to include the last_seen value for the user.
Returns:
json:
{"allow_guest": 1,
"deleted_user": 0,
"do_notify": 1,
"email": "Jon.Snow.1337@CastleBlack.com",
"friendly_name": "Jon Snow",
"is_active": 1,
"is_admin": 0,
"is_allow_sync": 1,
"is_home_user": 1,
"is_restricted": 0,
"keep_history": 1,
"last_seen": 1462591869,
"row_id": 1,
"shared_libraries": ["10", "1", "4", "5", "15", "20", "2"],
"user_id": 133788,
"user_thumb": "https://plex.tv/users/k10w42309cynaopq/avatar",
"username": "LordCommanderSnow"
}
Get the data on Tautulli users IP table.
Required parameters:
user_id (str): The id of the Plex user
Optional parameters:
order_column (str): "last_seen", "first_seen", "ip_address", "platform",
"player", "last_played", "play_count"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "xxx.xxx.xxx.xxx"
Returns:
json:
{"draw": 1,
"recordsTotal": 2344,
"recordsFiltered": 10,
"data":
[{"friendly_name": "Jon Snow",
"guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en",
"id": 1121,
"ip_address": "xxx.xxx.xxx.xxx",
"last_played": "Game of Thrones - The Red Woman",
"last_seen": 1462591869,
"first_seen": 1583968210,
"live": 0,
"media_index": 1,
"media_type": "episode",
"originally_available_at": "2016-04-24",
"parent_media_index": 6,
"parent_title": "",
"platform": "Chrome",
"play_count": 149,
"player": "Plex Web (Chrome)",
"rating_key": 153037,
"thumb": "/library/metadata/153036/thumb/1462175062",
"transcode_decision": "transcode",
"user_id": 133788,
"year": 2016
},
{...},
{...}
]
}
Get the data on Tautulli user login table.
Required parameters:
user_id (str): The id of the Plex user
Optional parameters:
order_column (str): "date", "time", "ip_address", "host", "os", "browser"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "xxx.xxx.xxx.xxx"
Returns:
json:
{"draw": 1,
"recordsTotal": 2344,
"recordsFiltered": 10,
"data":
[{"browser": "Safari 7.0.3",
"current": false,
"expiry": "2021-06-30 18:48:03",
"friendly_name": "Jon Snow",
"host": "http://plexpy.castleblack.com",
"ip_address": "xxx.xxx.xxx.xxx",
"os": "Mac OS X",
"row_id": 1,
"timestamp": 1462591869,
"user": "LordCommanderSnow",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A",
"user_group": "guest",
"user_id": 133788
},
{...},
{...}
]
}
Get a list of all user and user ids.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"friendly_name": "Jon Snow", "user_id": 133788},
{"friendly_name": "DanyKhaleesi69", "user_id": 8008135},
{"friendly_name": "Tyrion Lannister", "user_id": 696969},
{...},
]
Get a user's player statistics.
Required parameters:
user_id (str): The id of the Plex user
Optional parameters:
grouping (int): 0 or 1
Returns:
json:
[{"platform": "Chrome",
"platform_name": "chrome",
"player_name": "Plex Web (Chrome)",
"result_id": 1,
"total_plays": 170,
"total_time": 349618
},
{"platform": "Chromecast",
"platform_name": "chromecast",
"player_name": "Chromecast",
"result_id": 2,
"total_plays": 42,
"total_time": 50185
},
{...},
{...}
]
Get a user's watch time statistics.
Required parameters:
user_id (str): The id of the Plex user
Optional parameters:
grouping (int): 0 or 1
query_days (str): Comma separated days, e.g. "1,7,30,0"
Returns:
json:
[{"query_days": 1,
"total_plays": 0,
"total_time": 0
},
{"query_days": 7,
"total_plays": 3,
"total_time": 15694
},
{"query_days": 30,
"total_plays": 35,
"total_time": 63054
},
{"query_days": 0,
"total_plays": 508,
"total_time": 1183080
}
]
Get a list of all users that have access to your server.
Required parameters:
None
Optional parameters:
None
Returns:
json:
[{"allow_guest": 1,
"do_notify": 1,
"email": "Jon.Snow.1337@CastleBlack.com",
"filter_all": "",
"filter_movies": "",
"filter_music": "",
"filter_photos": "",
"filter_tv": "",
"is_active": 1,
"is_admin": 0,
"is_allow_sync": 1,
"is_home_user": 1,
"is_restricted": 0,
"keep_history": 1,
"row_id": 1,
"shared_libraries": ["1", "2", "3"],
"thumb": "https://plex.tv/users/k10w42309cynaopq/avatar",
"user_id": "133788",
"username": "Jon Snow"
},
{...},
{...}
]
Get the data on Tautulli users table.
Required parameters:
None
Optional parameters:
grouping (int): 0 or 1
order_column (str): "user_thumb", "friendly_name", "last_seen", "ip_address", "platform",
"player", "last_played", "plays", "duration"
order_dir (str): "desc" or "asc"
start (int): Row to start from, 0
length (int): Number of items to return, 25
search (str): A string to search for, "Jon Snow"
Returns:
json:
{"draw": 1,
"recordsTotal": 10,
"recordsFiltered": 10,
"data":
[{"allow_guest": 1,
"do_notify": 1,
"duration": 2998290,
"email": "Jon.Snow.1337@CastleBlack.com",
"friendly_name": "Jon Snow",
"guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en",
"history_row_id": 1121,
"ip_address": "xxx.xxx.xxx.xxx",
"is_active": 1,
"keep_history": 1,
"last_played": "Game of Thrones - The Red Woman",
"last_seen": 1462591869,
"live": 0,
"media_index": 1,
"media_type": "episode",
"originally_available_at": "2016-04-24",
"parent_media_index": 6,
"parent_title": "",
"platform": "Chrome",
"player": "Plex Web (Chrome)",
"plays": 487,
"rating_key": 153037,
"row_id": 1,
"thumb": "/library/metadata/153036/thumb/1462175062",
"title": "Jon Snow",
"transcode_decision": "transcode",
"user_id": 133788,
"user_thumb": "https://plex.tv/users/568gwwoib5t98a3a/avatar",
"username": "LordCommanderSnow",
"year": 2016
},
{...},
{...}
]
}
Get the connection info for an IP address.
Required parameters:
ip_address
Optional parameters:
None
Returns:
json:
{"host": "google-public-dns-a.google.com",
"nets": [{"description": "Google Inc.",
"address": "1600 Amphitheatre Parkway",
"city": "Mountain View",
"state": "CA",
"postal_code": "94043",
"country": "United States",
...
},
{...}
]
json:
{"host": "Not available",
"nets": [],
"error": "IPv4 address 127.0.0.1 is already defined as Loopback via RFC 1122, Section 3.2.1.3."
}
Import a Tautulli config file.
Required parameters:
config_file (file): The config file to import (multipart/form-data)
or
config_path (str): The full path to the config file to import
Optional parameters:
backup (bool): true or false whether to backup
the current config before importing
Returns:
json:
{"result": "success",
"message": "Config import has started. Check the logs to monitor any problems. "
"Tautulli will restart automatically."
}
Import a Tautulli, PlexWatch, or Plexivity database into Tautulli.
Required parameters:
app (str): "tautulli" or "plexwatch" or "plexivity"
database_file (file): The database file to import (multipart/form-data)
or
database_path (str): The full path to the database file to import
method (str): For Tautulli only, "merge" or "overwrite"
table_name (str): For PlexWatch or Plexivity only, "processed" or "grouped"
Optional parameters:
backup (bool): For Tautulli only, true or false whether to backup
the current database before importing
import_ignore_interval (int): For PlexWatch or Plexivity only, the minimum number
of seconds for a stream to import
Returns:
json:
{"result": "success",
"message": "Database import has started. Check the logs to monitor any problems."
}
Logout Tautulli user sessions.
Required parameters:
row_ids (str): Comma separated row ids to sign out, e.g. "2,3,8"
Optional parameters:
None
Returns:
None
Send a notification using Tautulli.
Required parameters:
notifier_id (int): The ID number of the notification agent
subject (str): The subject of the message
body (str): The body of the message
Optional parameters:
headers (str): The JSON headers for webhook notifications
script_args (str): The arguments for script notifications
Returns:
json:
{"notification_id": 1}
Send a newsletter using Tautulli.
Required parameters:
newsletter_id (int): The ID number of the newsletter agent
Optional parameters:
subject (str): The subject of the newsletter
body (str): The body of the newsletter
message (str): The message of the newsletter
Returns:
json:
{"newsletter_notification_id": 1}
Send a recently added notification using Tautulli.
Required parameters:
rating_key (int): The rating key for the media
Optional parameters:
notifier_id (int): The ID number of the notification agent.
The notification will send to all enabled notification agents if notifier id is not provided.
Returns:
json
{"result": "success",
"message": "Notification queued."
}
Gets an image from the PMS and saves it to the image cache directory.
Required parameters:
img (str): /library/metadata/153037/thumb/1462175060
or
rating_key (str): 54321
Optional parameters:
width (str): 300
height (str): 450
opacity (str): 25
background (str): Hex color, e.g. 282828
blur (str): 3
img_format (str): png
fallback (str): "poster", "cover", "art", "poster-live", "art-live", "art-live-full", "user"
refresh (bool): True or False whether to refresh the image cache
return_hash (bool): True or False to return the self-hosted image hash instead of the image
Returns:
None
Refresh the Tautulli libraries list.
Refresh the Tautulli users list.
Registers the Tautulli Remote App.
Required parameters:
device_id (str): The unique device identifier for the mobile device
device_name (str): The device name of the mobile device
Optional parameters:
platform (str): The platform of the mobile devices
version (str): The version of the app
friendly_name (str): A friendly name to identify the mobile device
onesignal_id (str): The OneSignal id for the mobile device
min_version (str): The minimum Tautulli version supported by the mobile device, e.g. v2.5.6
Returns:
json:
{"pms_identifier": "08u2phnlkdshf890bhdlksghnljsahgleikjfg9t",
"pms_ip": "10.10.10.1",
"pms_is_remote": 0,
"pms_name": "Winterfell-Server",
"pms_platform": "Windows",
"pms_plexpass": 1,
"pms_port": 32400,
"pms_ssl": 0,
"pms_url": "http://10.10.10.1:32400",
"pms_url_manual": 0,
"pms_version": "1.20.0.3133-fede5bdc7"
"server_id": "2ce060c87958445d8399a7a0c5663755",
"tautulli_install_type": "git",
"tautulli_branch": "master",
"tautulli_commit": "14b98a32e085d969f010f0249c3d2f660db50880",
"tautulli_platform": "Windows",
"tautulli_platform_device_name": "Winterfell-PC",
"tautulli_platform_linux_distro": "",
"tautulli_platform_release": "10",
"tautulli_platform_version": "10.0.18362",
"tautulli_python_version": "3.8.3"
"tautulli_version": "v2.5.6",
}
Regroup play history in the database.
Restart Tautulli.
Get search results from the PMS.
Required parameters:
query (str): The query string to search for
Optional parameters:
limit (int): The maximum number of items to return per media type
Returns:
json:
{"results_count": 69,
"results_list":
{"movie":
[{...},
{...},
]
},
{"episode":
[{...},
{...},
]
},
{...}
}
Get the current status of Tautulli's connection to the Plex server.
Required parameters:
None
Optional parameters:
None
Returns:
json:
{"result": "success",
"connected": true,
}
Configure an existing notification agent.
Required parameters:
mobile_device_id (int): The mobile device config to update
Optional parameters:
friendly_name (str): A friendly name to identify the mobile device
Returns:
None
Configure an existing newsletter agent.
Required parameters:
newsletter_id (int): The newsletter config to update
agent_id (int): The newsletter type of the newsletter
Optional parameters:
Pass all the config options for the agent with the 'newsletter_config_' and 'newsletter_email_' prefix.
Returns:
None
Configure an existing notification agent.
Required parameters:
notifier_id (int): The notifier config to update
agent_id (int): The agent of the notifier
Optional parameters:
Pass all the config options for the agent with the agent prefix:
e.g. For Telegram: telegram_bot_token
telegram_chat_id
telegram_disable_web_preview
telegram_html_support
telegram_incl_poster
telegram_incl_subject
Notify actions (int): 0 or 1,
e.g. on_play, on_stop, etc.
Notify text (str):
e.g. on_play_subject, on_play_body, etc.
Returns:
None
Query the Tautulli database with raw SQL. Automatically makes a backup of
the database if the latest backup is older then 24h. api_sql must be
manually enabled in the config file while Tautulli is shut down.
Required parameters:
query (str): The SQL query
Optional parameters:
None
Returns:
None
Get the current status of Tautulli.
Required parameters:
None
Optional parameters:
check (str): database
Returns:
json:
{"result": "success",
"message": "Ok",
}
Stop a streaming session.
Required parameters:
session_key (int): The session key of the session to terminate, OR
session_id (str): The session id of the session to terminate
Optional parameters:
message (str): A custom message to send to the client
Returns:
None
Restore a deleted library section to Tautulli.
Required parameters:
section_id (str): The id of the Plex library section
section_name (str): The name of the Plex library section
Optional parameters:
None
Returns:
None
Restore a deleted user to Tautulli.
Required parameters:
user_id (str): The id of the Plex user
username (str): The username of the Plex user
Optional parameters:
None
Returns:
None
Update Tautulli.
Check for Tautulli updates.
Required parameters:
None
Optional parameters:
None
Returns:
json
{"result": "success",
"update": true,
"message": "An update for Tautulli is available."
}
Update the metadata in the Tautulli database by matching rating keys. Also updates all parents or children of the media item if it is a show/season/episode or artist/album/track.
Required parameters:
old_rating_key (str): 12345
new_rating_key (str): 54321
media_type (str): "movie", "show", "season", "episode", "artist", "album", "track"
Optional parameters:
None
Returns:
None