# API Reference ## General structure 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 ``` ## API methods ### add\_newsletter\_config Add a new notification agent. ``` Required parameters: agent_id (int): The newsletter type to add Optional parameters: None Returns: None ``` ### add\_notifier\_config Add a new notification agent. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` Required paramters: None Optional parameters: None Returns: None ``` ### delete\_lookup\_info 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\_media\_info\_cache 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 ``` ### delete\_mobile\_device 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 ``` ### delete\_newsletter Remove a newsletter from the database. ``` Required parameters: newsletter_id (int): The newsletter to delete Optional parameters: None Returns: None ``` ### delete\_newsletter\_log Delete the Tautulli newsletter logs. ``` Required paramters: None Optional parameters: None Returns: None ``` ### delete\_notification\_log Delete the Tautulli notification logs. ``` Required paramters: None Optional parameters: None Returns: None ``` ### delete\_notifier Remove a notifier from the database. ``` 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. ``` 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. ``` 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 ``` 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. ``` 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. ``` 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 ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` Required parameters: None Optional parameters: None Returns: json: { } ``` ### get\_notifiers 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\_old\_rating\_keys 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\_playlists\_table 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\_plays\_by\_date 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): 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` Required parameters: None Optional parameters: None Returns: string: "Winterfell-Server" ``` ### get\_server\_id 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\_server\_identity 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\_server\_info 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\_server\_list 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\_server\_pref Get a specified PMS server preference. ``` Required parameters: pref (str): Name of preference Returns: string: Value of preference ``` ### get\_servers\_info 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" } ] ``` ### get\_settings 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\_stream\_data 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\_stream\_type\_by\_top\_10\_platforms 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): 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` 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. ``` Required parameters: None Optional parameters: None Returns: json: {"result": "success", "connected": true, } ``` ### set\_mobile\_device\_config 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 ``` ### set\_newsletter\_config 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 ``` ### set\_notifier\_config 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 ``` ### 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. ``` Required parameters: query (str): The SQL query Optional parameters: None Returns: None ``` ### status Get the current status of Tautulli. ``` Required parameters: None Optional parameters: check (str): database Returns: json: {"result": "success", "message": "Ok", } ``` ### terminate\_session 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 ``` ### undelete\_library 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 ``` ### undelete\_user 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 Update Tautulli. ### update\_check Check for Tautulli updates. ``` 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. ``` 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tautulli.com/extending-tautulli/api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.