# API Reference ## General structure The API endpoint is ```text http://IP_ADDRESS:PORT + [/HTTP_ROOT] + /api/v2?apikey=$apikey&cmd=$command ``` Example: ```text http://localhost:8181/api/v2?apikey=66198313a092496b8a725867d2223b5f&cmd=get_metadata&rating_key=153037 ``` Response example \(default `json`\) ```text { "response": { "data": [ { "loglevel": "INFO", "msg": "Signal 2 caught, saving and exiting...", "thread": "MainThread", "time": "22-sep-2015 01:42:56 " } ], "message": null, "result": "success" } } ``` ```text General optional parameters: out_type: "json" or "xml" callback: "pong" debug: 1 ``` ## API methods ### add\_newsletter\_config Add a new notification agent. ```text Required parameters: agent_id (int): The newsletter type to add Optional parameters: None Returns: None ``` ### add\_notifier\_config Add a new notification agent. ```text Required parameters: agent_id (int): The notification agent to add Optional parameters: None Returns: None ``` ### arnold Get to the chopper! ### backup\_config Create a manual backup of the `config.ini` file. ### backup\_db Create a manual backup of the `plexpy.db` file. ### delete\_all\_library\_history Delete all Tautulli history for a specific library. ```text 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\_user\_history Delete all Tautulli history for a specific user. ```text 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\_cache Delete and recreate the cache directory. ### delete\_export Delete exports from Tautulli. ```text 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 Delete history rows from Tautulli. ```text Required parameters: row_ids (str): Comma separated row ids to delete, e.g. "65,110,2,3645" Optional parameters: None Returns: None ``` ### delete\_hosted\_images Delete the images uploaded to image hosting services. ```text 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\_image\_cache Delete and recreate the image cache directory. ### delete\_library Delete a library section from Tautulli. Also erases all history for the library. ```text 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\_login\_log Delete the Tautulli login logs. ```text Required paramters: None Optional parameters: None Returns: None ``` ### delete\_lookup\_info Delete the 3rd party API lookup info. ```text 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\_media\_info\_cache Delete the media info table cache for a specific library. ```text Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: None ``` ### delete\_mobile\_device Remove a mobile device from the database. ```text 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 ``` ### delete\_newsletter Remove a newsletter from the database. ```text Required parameters: newsletter_id (int): The newsletter to delete Optional parameters: None Returns: None ``` ### delete\_newsletter\_log Delete the Tautulli newsletter logs. ```text Required paramters: None Optional parameters: None Returns: None ``` ### delete\_notification\_log Delete the Tautulli notification logs. ```text Required paramters: None Optional parameters: None Returns: None ``` ### delete\_notifier Remove a notifier from the database. ```text Required parameters: notifier_id (int): The notifier to delete Optional parameters: None Returns: None ``` ### delete\_recently\_added Flush out all of the recently added items in the database. ### delete\_synced\_item Delete a synced item from a device. ```text 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 ``` ### delete\_temp\_sessions Flush out all of the temporary sessions in the database. ### delete\_user Delete a user from Tautulli. Also erases all history for the user. ```text 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 ``` ### docs Return the api docs as a dict where commands are keys, docstring are value. ### docs\_md Return the api docs formatted with markdown. ### download\_config Download the Tautulli configuration file. ### download\_database Download the Tautulli database file. ### download\_export Download an exported metadata file ```text Required parameters: export_id (int): The row id of the exported file to download Optional parameters: None Returns: download ``` ### download\_log Download the Tautulli log file. ### download\_plex\_log Download the Plex log file. ### edit\_library Update a library section on Tautulli. ```text 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 ``` ### edit\_user Update a user on Tautulli. ```text 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\_metadata Export library or media metadata to a file ```text 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 m3u8 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: {"result": "success", "message": "Metadata export has started." } ``` ### get\_activity Get the current activity on the PMS. ```text 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_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\_apikey Get the apikey. Username and password are required if auth is enabled. Makes and saves the apikey if it does not exist. ```text Required parameters: None Optional parameters: username (str): Your Tautulli username password (str): Your Tautulli password Returns: string: "apikey" ``` ### get\_children\_metadata Get the metadata for the children of a media item. ```text 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": "", "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\_collections\_table Get the data on the Tautulli collections tables. ```text Required parameters: section_id (str): The id of the Plex library section Optional parameters: None Returns: json: {"draw": 1, "recordsTotal": 5, "data": [...] } ``` ### get\_date\_formats Get the date and time formats used by Tautulli. ```text Required parameters: None Optional parameters: None Returns: json: {"date_format": "YYYY-MM-DD", "time_format": "HH:mm", } ``` ### get\_export\_fields Get a list of available custom export fields. ```text 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\_exports\_table Get the data on the Tautulli export tables. ```text 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\_geoip\_lookup Get the geolocation info for an IP address. ```text Required parameters: ip_address Optional parameters: None Returns: json: {"code": 'US", "country": "United States", "region": "California", "city": "Mountain View", "postal_code": "94035", "timezone": "America/Los_Angeles", "latitude": 37.386, "longitude": -122.0838, "accuracy": 1000 } ``` ### get\_history Get the Tautulli history. ```text 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): "YYYY-MM-DD" section_id (int): 2 media_type (str): "movie", "episode", "track", "live" 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, "duration": 263, "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, "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", "product": "Plex for Windows", "player": "Castle-PC", "rating_key": 4348, "reference_id": 1123, "row_id": 1124, "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\_home\_stats Get the homepage watch statistics. ```text 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' 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": "", "platform_type": "", "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\_libraries Get a list of all libraries on your server. ```text 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\_libraries\_table Get the data on the Tautulli libraries table. ```text 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": "Checked", "do_notify_created": "Checked", "duration": 1578037, "guid": "com.plexapp.agents.thetvdb://121361/6/1?lang=en", "histroy_row_id": 1128, "is_active": 1, "keep_history": "Checked", "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\_library Get a library's details. ```text 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\_library\_media\_info Get the data on the Tautulli media info tables. ```text 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, "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\_library\_names Get a list of library sections and ids on the PMS. ```text 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\_library\_user\_stats Get a library's user statistics. ```text 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, "user_id": 133788, "user_thumb": "https://plex.tv/users/k10w42309cynaopq/avatar", "username": "LordCommanderSnow" }, {"friendly_name": "DanyKhaleesi69", "total_plays": 42, "user_id": 8008135, "user_thumb": "https://plex.tv/users/568gwwoib5t98a3a/avatar", "username: "DanyKhaleesi69" }, {...}, {...} ] ``` ### get\_library\_watch\_time\_stats Get a library's watch time statistics. ```text 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\_logs Get the Tautulli logs. ```text 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\_metadata Get the metadata for a media item. ```text 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": [ "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", "collections": [], "content_rating": "TV-MA", "directors": [ "Jeremy Podeswa" ], "duration": "2998290", "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/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", "live": 0, "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_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": "com.plexapp.agents.thetvdb://121361/6?lang=en", "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\_new\_rating\_keys Get a list of new rating keys for the PMS of all of the item's parent/children. ```text Required parameters: rating_key (str): '12345' media_type (str): "movie", "show", "season", "episode", "artist", "album", "track" Optional parameters: None Returns: json: {} ``` ### get\_newsletter\_config Get the configuration for an existing notification agent. ```text 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\_newsletter\_log Get the data on the Tautulli newsletter logs table. ```text 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\_newsletters Get a list of configured newsletters. ```text 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\_notification\_log Get the data on the Tautulli notification logs table. ```text 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\_notifier\_config Get the configuration for an existing notification agent. ```text 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\_notifier\_parameters Get the list of available notification parameters. ```text Required parameters: None Optional parameters: None Returns: json: { } ``` ### get\_notifiers Get a list of configured notifiers. ```text 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\_old\_rating\_keys Get a list of old rating keys from the Tautulli database for all of the item's parent/children. ```text Required parameters: rating_key (str): '12345' media_type (str): "movie", "show", "season", "episode", "artist", "album", "track" Optional parameters: None Returns: json: {} ``` ### get\_playlists\_table Get the data on the Tautulli playlists tables. ```text 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\_plays\_by\_date Get graph data by date. ```text 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): The 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\_plays\_by\_dayofweek Get graph data by day of the week. ```text 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): The 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\_plays\_by\_hourofday Get graph data by hour of the day. ```text 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): The 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\_plays\_by\_source\_resolution Get graph data by source resolution. ```text 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): The 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\_plays\_by\_stream\_resolution Get graph data by stream resolution. ```text 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): The 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\_plays\_by\_stream\_type Get graph data by stream type by date. ```text 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): The 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\_plays\_by\_top\_10\_platforms Get graph data by top 10 platforms. ```text 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): The 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\_plays\_by\_top\_10\_users Get graph data by top 10 users. ```text 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): The 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\_plays\_per\_month Get graph data by month. ```text 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): The 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\_plex\_log Get the PMS logs. ```text Required parameters: None Optional parameters: window (int): The number of tail lines to return log_type (str): "server" or "scanner" Returns: json: [["May 08, 2016 09:35:37", "DEBUG", "Auth: Came in with a super-token, authorization succeeded." ], [...], [...] ] ``` ### get\_pms\_update Check for updates to the Plex Media Server. ```text 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\_recently\_added Get all items that where recently added to plex. ```text 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\_server\_friendly\_name Get the name of the PMS. ```text Required parameters: None Optional parameters: None Returns: string: "Winterfell-Server" ``` ### get\_server\_id Get the PMS server identifier. ```text 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\_server\_identity Get info about the local server. ```text Required parameters: None Optional parameters: None Returns: json: [{"machine_identifier": "ds48g4r354a8v9byrrtr697g3g79w", "version": "0.9.15.x.xxx-xxxxxxx" } ] ``` ### get\_server\_info Get the PMS server information. ```text 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\_server\_list Get all your servers that are published to Plex.tv. ```text 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\_server\_pref Get a specified PMS server preference. ```text Required parameters: pref (str): Name of preference Returns: string: Value of preference ``` ### get\_servers\_info Get info about the PMS. ```text 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" } ] ``` ### get\_settings Gets all settings from the config file. ```text 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\_stream\_data Get the stream details from history or current stream. ```text 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\_stream\_type\_by\_top\_10\_platforms Get graph data by stream type by top 10 platforms. ```text 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): The 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\_stream\_type\_by\_top\_10\_users Get graph data by stream type by top 10 users. ```text 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): The 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\_synced\_items Get a list of synced items on the PMS. ```text 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\_user Get a user's details. ```text 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\_user\_ips Get the data on Tautulli users IP table. ```text 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\_user\_logins Get the data on Tautulli user login table. ```text 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\_user\_names Get a list of all user and user ids. ```text 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\_user\_player\_stats Get a user's player statistics. ```text Required parameters: user_id (str): The id of the Plex user Optional parameters: grouping (int): 0 or 1 Returns: json: [{"platform_type": "Chrome", "player_name": "Plex Web (Chrome)", "result_id": 1, "total_plays": 170 }, {"platform_type": "Chromecast", "player_name": "Chromecast", "result_id": 2, "total_plays": 42 }, {...}, {...} ] ``` ### get\_user\_watch\_time\_stats Get a user's watch time statistics. ```text 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\_users Get a list of all users that have access to your server. ```text 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, "server_token": "PU9cMuQZxJKFBtGqHk68", "shared_libraries": "1;2;3", "thumb": "https://plex.tv/users/k10w42309cynaopq/avatar", "user_id": "133788", "username": "Jon Snow" }, {...}, {...} ] ``` ### get\_users\_table Get the data on Tautulli users table. ```text 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": "Checked", "do_notify": "Checked", "duration": 2998290, "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": "Checked", "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", "transcode_decision": "transcode", "user_id": 133788, "user_thumb": "https://plex.tv/users/568gwwoib5t98a3a/avatar", "username": "LordCommanderSnow", "year": 2016 }, {...}, {...} ] } ``` ### get\_whois\_lookup Get the connection info for an IP address. ```text 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\_config Import a Tautulli config file. ```text 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\_database Import a Tautulli, PlexWatch, or Plexivity database into Tautulli. ```text 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\_user\_session Logout Tautulli user sessions. ```text Required parameters: row_ids (str): Comma separated row ids to sign out, e.g. "2,3,8" Optional parameters: None Returns: None ``` ### notify Send a notification using Tautulli. ```text 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: None ``` ### notify\_newsletter Send a newsletter using Tautulli. ```text 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: None ``` ### notify\_recently\_added Send a recently added notification using Tautulli. ```text 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." } ``` ### pms\_image\_proxy Gets an image from the PMS and saves it to the image cache directory. ```text 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\_libraries\_list Refresh the Tautulli libraries list. ### refresh\_users\_list Refresh the Tautulli users list. ### register\_device Registers the Tautulli Android App for notifications. ```text 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: 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", } ``` ### restart Restart Tautulli. ### search Get search results from the PMS. ```text 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": [{...}, {...}, ] }, {...} } ``` ### server\_status Get the current status of Tautulli's connection to the Plex server. ```text Required parameters: None Optional parameters: None Returns: json: {"result": "success", "connected": true, } ``` ### set\_mobile\_device\_config Configure an existing notification agent. ```text 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 ``` ### set\_newsletter\_config Configure an existing newsletter agent. ```text 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 ``` ### set\_notifier\_config Configure an existing notification agent. ```text 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 ``` ### sql 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. ```text Required parameters: query (str): The SQL query Optional parameters: None Returns: None ``` ### status Get the current status of Tautulli. ```text Required parameters: None Optional parameters: check (str): database Returns: json: {"result": "success", "message": "Ok", } ``` ### terminate\_session Stop a streaming session. ```text 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 ``` ### undelete\_library Restore a deleted library section to Tautulli. ```text 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 ``` ### undelete\_user Restore a deleted user to Tautulli. ```text 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 Update Tautulli. ### update\_check Check for Tautulli updates. ```text Required parameters: None Optional parameters: None Returns: json {"result": "success", "update": true, "message": "An update for Tautulli is available." } ``` ### update\_metadata\_details 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. ```text 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 ```