# Trakt Public API Documentation > Documentation for Trakt Public API Fetch the complete documentation index at: https://docs.trakt.tv/llms.txt. Use this file to discover all available pages before exploring further. ## API Reference - [Authentication](https://docs.trakt.tv/reference/auth.md) - [Generate new device codes](https://docs.trakt.tv/reference/postoauthdevicecode.md): Generate new codes to start the device authentication process. The `device_code` and `interval` will be used later to poll for the `access_token`. The `user_code` and `verification_url` should be presented to the user as mentioned in the flow steps above. #### QR Code You might consider generating a QR code for the user to easily scan on their mobile device. The QR code should be a URL that redirects to the `verification_url` and appends the `user_code`. For example, `https://trakt.tv/activate/5055CC52` would load the Trakt hosted `verification_url` and pre-fill in the `user_code`. #### JSON POST Data | Key | Type | Value | |---|---|---| | `client_id` * | string | Get this from your app settings. | - [Poll for the access_token](https://docs.trakt.tv/reference/postoauthdevicetoken.md): Use the `device_code` and poll at the `interval` (in seconds) to check if the user has authorized you app. Use `expires_in` to stop polling after that many seconds, and gracefully instruct the user to restart the process. **It is important to poll at the correct interval and also stop polling when expired.** When you receive a `200` success response, save the `access_token` so your app can authenticate the user in methods that require it. The `access_token` is valid for **7 days**. Save and use the `refresh_token` to get a new `access_token` without asking the user to re-authenticate. Check below for all the error codes that you should handle. #### JSON POST Data | Key | Type | Value | |---|---|---| | `code` * | string | `device_code` from the initial method. | | `client_id` * | string | Get this from your app settings. | | `client_secret` * | string | Get this from your app settings. | #### Status Codes This method will send various HTTP status codes that you should handle accordingly. | Code | Description | |---|---| | `200` | Success - *save the `access_token`* | `400` | Pending - *waiting for the user to authorize your app* | `404` | Not Found - *invalid `device_code`* | `409` | Already Used - *user already approved this code* | `410` | Expired - *the tokens have expired, restart the process* | `418` | Denied - *user explicitly denied this code* | `429` | Slow Down - *your app is polling too quickly* - [Exchange a token](https://docs.trakt.tv/reference/postoauthtoken.md): Exchange an OAuth authorization code or refresh token for an access token. #### Refreshing Tokens Refresh tokens are single-use. Each successful refresh returns a new `refresh_token` and invalidates the previous one. Store the new `access_token` and `refresh_token` from the response before the next refresh. If the exchange cannot be completed, this endpoint returns a `400` response with an OAuth error and description. - [Authorize Application](https://docs.trakt.tv/reference/getoauthauthorize.md): Construct then redirect to this URL. The Trakt website will request permissions for your app, which the user needs to approve. If the user isn't signed into Trakt, it will ask them to do so. > ### Important > _Use the **https://auth.trakt.tv** hostname for all OAuth requests, including authorization, device authentication, token exchange and refresh, and token revocation. Do not use the API hostname for these requests._ #### Optional URL Parameters When building the authorization URL, you can optionally include the following query parameters in the URL. | Parameter | Value | Description | |---|---|---| | `signup` | `true` | Prefer the account sign up page to be the default. | | `prompt` | `login` | Force the user to sign in and authorize your app. | - [Revoke an access_token](https://docs.trakt.tv/reference/postoauthrevoke.md): An `access_token` can be revoked when a user signs out of their Trakt account in your app. This is not required, but might improve the user experience so the user doesn't have an unused app connection hanging around. #### JSON POST Data | Key | Type | Value | |---|---|---| | `token` * | string | A valid OAuth `access_token`. | | `client_id` * | string | Get this from your app settings. | | `client_secret` * | string | Get this from your app settings. | - [About Calendars](https://docs.trakt.tv/reference/about-calendars.md) - [Get shows](https://docs.trakt.tv/reference/getcalendarsshows.md): #### ✨ Extended Info 🎚 Filters Returns shows airing during the requested UTC date range. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`), and send `start_date` and `days` to define the window. - [Get new shows](https://docs.trakt.tv/reference/getcalendarsnewshows.md): #### ✨ Extended Info 🎚 Filters Returns new shows airing their first season during the requested UTC date range. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`). - [Get season premieres](https://docs.trakt.tv/reference/getcalendarsseasonpremieres.md): #### ✨ Extended Info 🎚 Filters Returns season premieres airing during the requested UTC date range. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`). - [Get finales](https://docs.trakt.tv/reference/getcalendarsfinales.md): #### ✨ Extended Info 🎚 Filters Returns show finales airing during the requested UTC date range. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`). - [Get movies](https://docs.trakt.tv/reference/getcalendarsmovies.md): #### ✨ Extended Info 🎚 Filters Returns movies with a release date during the requested UTC date range. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`). - [Get DVD releases](https://docs.trakt.tv/reference/getcalendarsdvdreleases.md): #### ✨ Extended Info 🎚 Filters Returns DVD and physical media releases during the requested UTC date range. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`). - [Get streaming releases](https://docs.trakt.tv/reference/getcalendarsstreaming.md): #### ✨ Extended Info 🎚 Filters Returns all movies with a streaming release date during the requested UTC date range. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`). - [Get hot releases](https://docs.trakt.tv/reference/getcalendarsreleaseshot.md): #### ✨ Extended Info 🎚 Filters Returns the merged feed of upcoming movies and episodes during the requested UTC date range that are trending or highly anticipated, ordered by availability date. This is the global feed only; use `type` to narrow to a single media type. - [Get media](https://docs.trakt.tv/reference/getcalendarsmedia.md): #### ✨ Extended Info 🎚 Filters Returns the merged feed of movies and episodes during the requested UTC date range, ordered by availability date. Use `target` to choose the authenticated user calendar (`my`) or the global calendar (`all`), and `type` to narrow to a single media type. - [Get hot premieres](https://docs.trakt.tv/reference/getcalendarsreleaseshotpremieres.md): #### ✨ Extended Info 🎚 Filters Returns upcoming show premieres during the requested UTC date range that are trending or highly anticipated. Curated global feed - daily-cadence formats (soap, talk, news, game shows) and specials are excluded. - [Get hot finales](https://docs.trakt.tv/reference/getcalendarsreleaseshotfinales.md): #### ✨ Extended Info 🎚 Filters Returns upcoming show finales during the requested UTC date range that are trending or highly anticipated. Curated global feed - daily-cadence formats (soap, talk, news, game shows) and specials are excluded. - [Get hot new shows](https://docs.trakt.tv/reference/getcalendarsreleaseshotnew.md): #### ✨ Extended Info 🎚 Filters Returns upcoming series premieres during the requested UTC date range that are trending or highly anticipated. Curated global feed - daily-cadence formats (soap, talk, news, game shows) and specials are excluded. - [About Checkin](https://docs.trakt.tv/reference/about-checkin.md) - [Delete any active checkins](https://docs.trakt.tv/reference/deletecheckindelete.md): #### 🔒 OAuth Required Removes any active checkins, no need to provide a specific item. - [Check into an item](https://docs.trakt.tv/reference/postcheckinstart.md): #### 🔒 OAuth Required Check into a movie or episode. This should be tied to a user action to manually indicate they are watching something. The item will display as *watching* on the site, then automatically switch to *watched* status once the duration has elapsed. A unique history `id` (64-bit integer) will be returned and can be used to reference this checkin directly. #### JSON POST Data | Key | Type | Value | |---|---|---| | item * | object | `movie` or `episode` object. (see examples ->) | | `sharing` | object | Control sharing to any connected social networks. (see below ↓) | | `message` | string | Message used for sharing. If not sent, it will use the watching string in the user settings. | #### Sharing The `sharing` object is optional and will apply the user's settings if not sent. If `sharing` is sent, each key will override the user's setting for that social network. Send `true` to post or `false` to not post on the indicated social network. You can see which social networks a user has connected with the [**/users/settings**](/reference/users/settings) method. | Key | Type | |---|---| | `twitter` | boolean | | `mastodon` | boolean | | `tumblr` | boolean | > ### Note > _If a checkin is already in progress, a `409` HTTP status code will returned. The response will contain an `expires_at` timestamp which is when the user can check in again._ - [Retrieve settings](https://docs.trakt.tv/reference/getuserssettings.md): #### 🔒 OAuth Required Get the user's settings so you can align your app's experience with what they're used to on the trakt website. A globally unique `uuid` is also returned, which can be used to identify the user locally in your app if needed. However, the `uuid` can't be used to retrieve data from the Trakt API. #### Limits The `limits` object is useful to customize your user experience. For example, if the user has a `list` limit of `2`, you might want to show a message to the user that they need to upgrade to [**Trakt VIP**](https://trakt.tv/vip) to add more lists. #### Permissions The `permissions` object is also useful to customize your user experience. In general, an account will have permissions to do everything. However, we'll temporarily set a permission to `false` if the user triggers spam protections. - [Update settings](https://docs.trakt.tv/reference/putuserssavesettings.md): #### 🔒 OAuth Required Update settings for the authenticated user. Send the settings request body with the values to change; a successful update returns no response body. - [Update avatar](https://docs.trakt.tv/reference/putusersavatar.md): #### 🔒 OAuth Required Update the authenticated user avatar. Send the avatar request body; a successful update returns a `204` response, and invalid image data returns `400`. - [Get user profile](https://docs.trakt.tv/reference/getusersprofile.md): #### 🔓 OAuth Optional ✨ Extended Info Get a user's profile information. If the user is private, info will only be returned if you send OAuth and are either that user or an approved follower. Adding `?extended=vip` will return some additional VIP related fields so you can display the user's Trakt VIP status and year count. - [Get social activity](https://docs.trakt.tv/reference/getusersactivities.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns recent activity for a user social graph. Use `type` to choose `friends`, `followers`, or `following`, and use pagination to move through the activity feed. - [Get stats](https://docs.trakt.tv/reference/getusersstats.md): #### 🔓 OAuth Optional Returns stats about the movies, shows, and episodes a user has watched, collected, and rated. - [Get comments](https://docs.trakt.tv/reference/getuserscomments.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns the most recently written comments for the user. You can optionally filter by the `comment_type` and media `type` to limit what gets returned. By default, only top level comments are returned. Set `?include_replies=true` to return replies in addition to top level comments. Set `?include_replies=only` to return only replies and no top level comments. - [Get watching](https://docs.trakt.tv/reference/getuserswatching.md): #### 🔓 OAuth Optional ✨ Extended Info Returns a movie or episode if the user is currently watching something. If they are not, it returns no data and a `204` HTTP status code. - [Follow this user](https://docs.trakt.tv/reference/postusersfollow.md): #### 🔒 OAuth Required If the user has a private profile, the follow request will require approval (`approved_at` will be null). If a user is public, they will be followed immediately (`approved_at` will have a date). > ### Note > _If this user is already being followed or there is a pending follow request, a `409` HTTP status code will returned._ - [Unfollow this user](https://docs.trakt.tv/reference/deleteusersunfollow.md): #### 🔒 OAuth Required Unfollow someone you already follow. - [Get followers](https://docs.trakt.tv/reference/getusersfollowers.md): #### 🔓 OAuth Optional ✨ Extended Info Returns all followers including when the relationship began. - [Get following](https://docs.trakt.tv/reference/getusersfollowing.md): #### 🔓 OAuth Optional ✨ Extended Info Returns all user's they follow including when the relationship began. - [Get friends](https://docs.trakt.tv/reference/getusersfriends.md): #### 🔓 OAuth Optional ✨ Extended Info Returns all friends for a user including when the relationship began. Friendship is a 2 way relationship where each user follows the other. - [Get watched history](https://docs.trakt.tv/reference/getusershistoryall.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns watched history for a user across all supported media types. Use `start_at` and `end_at` to limit results to a UTC datetime range. - [Get movie watched history](https://docs.trakt.tv/reference/getusershistorymovies.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns movie watched history for a user. Use `start_at` and `end_at` to limit results to a UTC datetime range. - [Get show watched history](https://docs.trakt.tv/reference/getusershistoryshows.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns show watched history for a user. Use `start_at` and `end_at` to limit results to a UTC datetime range. - [Get episode watched history](https://docs.trakt.tv/reference/getusershistoryepisodes.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns episode watched history for a user. Use `start_at` and `end_at` to limit results to a UTC datetime range. - [Get history for a movie](https://docs.trakt.tv/reference/getusershistorymovie.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns watched history entries for one movie. Use `item_id` to identify the movie and `start_at` or `end_at` to limit the date range. - [Get history for a show](https://docs.trakt.tv/reference/getusershistoryshow.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns watched history entries for one show. Use `item_id` to identify the show and `start_at` or `end_at` to limit the date range. - [Get history for an episode](https://docs.trakt.tv/reference/getusershistoryepisode.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns watched history entries for one episode. Use `item_id` to identify the episode and `start_at` or `end_at` to limit the date range. - [Get movie watchlist](https://docs.trakt.tv/reference/getuserswatchlistmovies.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns movies on a user watchlist. Use the `sort` path parameter plus query sorting, pagination, and filters to control the result order and contents. - [Get show watchlist](https://docs.trakt.tv/reference/getuserswatchlistshows.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns shows on a user watchlist. Use the `sort` path parameter plus query sorting, pagination, and filters to control the result order and contents. - [Get all watchlist comments](https://docs.trakt.tv/reference/getuserswatchlistcomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for the watchlist. By default, the comments are sorted by most `likes`. Other sorting options include `likes_30`, most `replies`, `replies_30`, most `plays`, highest `rating`, and `added` date. > ### Note > _If you send OAuth, comments from blocked users will be automatically filtered out._ - [Get movie ratings](https://docs.trakt.tv/reference/getusersratingsmovies.md): #### 🔓 OAuth Optional ✨ Extended Info Returns movies rated by a user including each rating value and when it was rated. - [Get show ratings](https://docs.trakt.tv/reference/getusersratingsshows.md): #### 🔓 OAuth Optional ✨ Extended Info Returns shows rated by a user including each rating value and when it was rated. - [Get episode ratings](https://docs.trakt.tv/reference/getusersratingsepisodes.md): #### 🔓 OAuth Optional ✨ Extended Info Returns episodes rated by a user including each rating value and when it was rated. - [Get favorite movies](https://docs.trakt.tv/reference/getusersfavoritesmovies.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns favorite movies for a user. Use the `sort` path parameter plus query sorting and pagination to control the result order. - [Get favorite shows](https://docs.trakt.tv/reference/getusersfavoritesshows.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns favorite shows for a user. Use the `sort` path parameter plus query sorting and pagination to control the result order. - [Get all favorites comments](https://docs.trakt.tv/reference/getusersfavoritescomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for the favorites. By default, the comments are sorted by most `likes`. Other sorting options include `likes_30`, most `replies`, `replies_30`, most `plays`, highest `rating`, and `added` date. > ### Note > _If you send OAuth, comments from blocked users will be automatically filtered out._ - [Get a user's personal lists](https://docs.trakt.tv/reference/getuserslistspersonal.md): #### 🔓 OAuth Optional 😁 Emojis Returns all personal lists for a user. Use the [**/users/:id/lists/:list_id/items**](#reference/users/list-items) method to get the actual items a specific list contains. - [Get all lists a user can collaborate on](https://docs.trakt.tv/reference/getuserslistscollaborations.md): #### 🔓 OAuth Optional Returns all lists a user can collaborate on. This gives full access to add, remove, and re-order list items. It essentially works just like a list owned by the user, just make sure to use the correct list owner `user` when building the API URLs. - [Reorder a user's lists](https://docs.trakt.tv/reference/postuserslistsreorder.md): #### 🔒 OAuth Required Reorder all lists by sending the updated `rank` of list ids. Use the [**/users/:id/lists**](#reference/users/lists) method to get all list ids. - [Get personal list](https://docs.trakt.tv/reference/getuserslistslistsummary.md): #### 🔓 OAuth Optional 😁 Emojis Returns a single personal list. Use the [**/users/:id/lists/:list_id/items**](#reference/users/list-items) method to get the actual items this list contains. - [Add items to personal list](https://docs.trakt.tv/reference/postuserslistslistadd.md): #### 🔥 VIP Enhanced 🔒 OAuth Required 😁 Emojis Add one or more items to a personal list. Items can be movies, shows, seasons, episodes, or people. #### Notes Each list item can optionally accept a `notes` *(500 maximum characters)* field with custom text. The user must be a [**Trakt VIP**](https://trakt.tv/vip) to send `notes`. #### Limits If the user's list item limit is exceeded, a `420` HTTP error code is returned. Use the [**/users/settings**](/reference/users/settings) method to get all limits for a user account. In most cases, upgrading to [**Trakt VIP**](https://trakt.tv/vip) will increase the limits. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | | `people` | array | Array of `person` objects. | - [Remove items from personal list](https://docs.trakt.tv/reference/postuserslistslistremove.md): #### 🔒 OAuth Required Remove one or more items from a personal list. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | | `people` | array | Array of `person` objects. | - [Reorder items on a list](https://docs.trakt.tv/reference/postuserslistslistreorder.md): #### 🔒 OAuth Required Reorder items on a personal list. Send the ordered list item IDs in the request body; the response returns the updated item order. - [Get all users who liked a list](https://docs.trakt.tv/reference/getuserslistslistlikes.md): #### 🔓 OAuth Optional 📄 Pagination Returns all users who liked a list. - [Get all list comments](https://docs.trakt.tv/reference/getuserslistslistcomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for a list. By default, the comments are sorted by most `likes`. Other sorting options include `likes_30`, most `replies`, `replies_30`, most `plays`, highest `rating`, and `added` date. > ### Note > _If you send OAuth, comments from blocked users will be automatically filtered out._ - [Add hidden items](https://docs.trakt.tv/reference/postusershiddenadd.md): #### 🔒 OAuth Required Hide items for a specific section. Here's what type of items can hidden for each section. You can optionally specify the `hidden_at` date for each item. #### Hideable Media Objects | Section | Objects | |---|---|---| | `calendar` | `movie`, `show` | | `progress_watched` | `show`, `season` | | `progress_collected` | `show`, `season` | | `recommendations` | `movie`, `show` | | `comments` | `user` | | `dropped` | `show` | #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `users` | array | Array of `user` objects. | - [Get hidden progress items](https://docs.trakt.tv/reference/getusershiddenget.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns shows hidden from watched progress for the authenticated user. Use `type`, `page`, and `limit` to filter and paginate the hidden items. - [Remove hidden progress items](https://docs.trakt.tv/reference/postusershiddenremoveprogress.md): #### 🔒 OAuth Required Remove shows or seasons from hidden watched progress. Send hideable media objects in the request body; the response contains remove counts. - [Remove hidden calendar items](https://docs.trakt.tv/reference/postusershiddenremovecalendar.md): #### 🔒 OAuth Required Remove movies or shows from hidden calendar items. Send hideable media objects in the request body; the response contains remove counts. - [Get follow requests](https://docs.trakt.tv/reference/getusersrequestsfollow.md): #### 🔒 OAuth Required ✨ Extended Info List a user's pending follow requests so they can either approve or deny them. - [Get pending following requests](https://docs.trakt.tv/reference/getusersrequestsfollowing.md): #### 🔒 OAuth Required ✨ Extended Info List a user's pending following requests that they're waiting for the other user's to approve. - [Approve follow request](https://docs.trakt.tv/reference/postusersrequestsapprove.md): #### 🔒 OAuth Required Approve a follower using the `id` of the request. If the `id` is not found, was already approved, or was already denied, a `404` error will be returned. - [Deny follow request](https://docs.trakt.tv/reference/deleteusersrequestsdeny.md): #### 🔒 OAuth Required Deny a follower using the `id` of the request. If the `id` is not found, was already approved, or was already denied, a `404` error will be returned. - [Get saved filters](https://docs.trakt.tv/reference/getusersfilterssaved.md): #### 🔥 VIP Only 🔒 OAuth Required 📄 Pagination Get all saved filters a user has created. The `path` and `query` can be used to construct an API path to retrieve the saved data. Think of this like a dynamically updated list. - [Get month in review](https://docs.trakt.tv/reference/getusersmonth_in_review.md): #### 🔓 OAuth Optional ✨ Extended Info Returns a month-in-review summary for a user. Send the `year` and `month` path parameters to choose the review period. - [Get media watchlist](https://docs.trakt.tv/reference/getuserswatchlistall.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns movies and shows on a user watchlist. Use the `sort` path parameter plus query sorting, pagination, and filters to control the result order and contents. - [Create personal list](https://docs.trakt.tv/reference/postuserslistscreate.md): #### 🔥 VIP Enhanced 🔒 OAuth Required Create a new personal list. The `name` is the only required field, but the other info is recommended to ask for. #### Limits If the user's list limit is exceeded, a `420` HTTP error code is returned. Use the [**/users/settings**](/reference/users/settings) method to get all limits for a user account. In most cases, upgrading to [**Trakt VIP**](https://trakt.tv/vip) will increase the limits. #### Privacy Lists will be `private` by default. Here is what each value means. | Value | Privacy impact... | |---|---| | `private` | Only you can see the list. | | `link` | Anyone with the `share_link` can see the list. | | `friends` | Only your friends can see the list. | | `public` | Anyone can see the list. | #### JSON POST Data | Key | Type | Default | Value | |---|---|---|---| | `name` * | string | | Name of the list. | | `description` | string | | Description for this list. | | `privacy` | string | `private` | `private`, `link`, `friends`, `public` | | `display_numbers` | boolean | `false` | Should each item be numbered? | | `allow_comments` | boolean | `true` | Are comments allowed? | | `sort_by` | string | `rank` | `rank`, `added`, `title`, `released`, `runtime`, `popularity`, `random`, `percentage`, `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, `tmdb_votes`, `my_rating`, `watched`, `collected` | | `sort_how` | string | `asc` | `asc`, `desc` | - [Update personal list](https://docs.trakt.tv/reference/putuserslistslistupdate.md): #### 🔒 OAuth Required Update a personal list by sending 1 or more parameters. If you update the list name, the original slug will still be retained so existing references to this list won't break. #### Privacy Lists will be `private` by default. Here is what each value means. | Value | Privacy impact... | |---|---| | `private` | Only you can see the list. | | `link` | Anyone with the `share_link` can see the list. | | `friends` | Only your friends can see the list. | | `public` | Anyone can see the list. | #### JSON POST Data | Key | Type | Value | |---|---|---|---| | `name` | string | Name of the list. | | `description` | string | Description for this list. | | `privacy` | string | `private`, `link`, `friends`, `public` | | `display_numbers` | boolean | Should each item be numbered? | | `allow_comments` | boolean | Are comments allowed? | | `sort_by` | string | `rank`, `added`, `title`, `released`, `runtime`, `popularity`, `random`, `percentage`, `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, `tmdb_votes`, `my_rating`, `watched`, `collected` | | `sort_how` | string | `asc`, `desc` | - [Delete a user's personal list](https://docs.trakt.tv/reference/deleteuserslistslistdelete.md): #### 🔒 OAuth Required Remove a personal list and all items it contains. - [Get movie list items](https://docs.trakt.tv/reference/getuserslistslistitemsmovie.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns movie items on a personal list. Use `list_id` to identify the list and query sorting, filters, and pagination to control the result set. - [Get show list items](https://docs.trakt.tv/reference/getuserslistslistitemsshow.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns show items on a personal list. Use `list_id` to identify the list and query sorting, filters, and pagination to control the result set. - [Get all list items](https://docs.trakt.tv/reference/getuserslistslistitemsall.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns movie, show, season, and episode items on a personal list. Use `list_id` to identify the list and query sorting, filters, and pagination to control the result set. - [Get comment reactions](https://docs.trakt.tv/reference/getusersreactionscomments.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns comments the authenticated user has reacted to. Use `extended`, `page`, and `limit` to control returned comment detail and pagination. - [Update cover image](https://docs.trakt.tv/reference/putuserscover.md): #### 🔒 OAuth Required Update the authenticated user cover image. Send the cover request body; a successful update returns a `204` response, and invalid image data returns `400`. - [Get watched movies](https://docs.trakt.tv/reference/getuserswatchedminimalmovies.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns movies watched by a user in a minimal paginated format. Use `extended`, `page`, and `limit` to control the response. - [Get year in review](https://docs.trakt.tv/reference/getusersyear_in_review.md): #### 🔓 OAuth Optional ✨ Extended Info Returns a year-in-review summary for a user. Send the `year` path parameter to choose the review period. - [Get media list items](https://docs.trakt.tv/reference/getuserslistslistitemsmedia.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns movie and show items on a personal list. Use `list_id` to identify the list and query sorting, filters, and pagination to control the result set. - [Add saved filters](https://docs.trakt.tv/reference/postusersfiltersadd.md): #### 🔥 VIP Only 🔒 OAuth Required Create saved filters for the authenticated user. Send filter names and URLs in the request body; the response returns the created filter records. - [Delete saved filter](https://docs.trakt.tv/reference/deleteusersfiltersdelete.md): #### 🔥 VIP Only 🔒 OAuth Required Delete a saved filter by `id`. A successful delete returns `204`; an unknown filter returns `404`. - [Get favorite media](https://docs.trakt.tv/reference/getusersfavoritesmedia.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns favorite movies and shows for a user. Use the `sort` path parameter plus query sorting and pagination to control the result order. - [Get dropped shows](https://docs.trakt.tv/reference/getusershiddendropped.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns shows the authenticated user has dropped or hidden from progress. Use pagination to move through the hidden dropped list. - [Get blocked users](https://docs.trakt.tv/reference/getusersblocked.md): #### 🔒 OAuth Required Returns all users you have blocked, including when each user was blocked. - [Block this user](https://docs.trakt.tv/reference/postusersblock.md): #### 🔒 OAuth Required Block a user. If they are already following you, they will be removed from your followers. Any pending follow request from this user will be blocked, preventing them from following you in the future until you unblock them. > ### Note > _If the user is already blocked, or you try to block yourself, a `409` HTTP status code will be returned._ - [Unblock this user](https://docs.trakt.tv/reference/deleteusersunblock.md): #### 🔒 OAuth Required Unblock a user you previously blocked. - [Report a user](https://docs.trakt.tv/reference/postusersreport.md): #### 🔒 OAuth Required Report a user for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per reported user. | reason | description | |---|---| | `spam` | Spam account | | `adult` | Adult content in profile | | `language` | Not using English | | `other` | Anything else (add details in `message`) | - [Get watched shows](https://docs.trakt.tv/reference/getuserswatchedminimalshows.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns shows watched by a user in a minimal paginated format. Use `specials` and `season_numbers` to control season details in the response. - [Get all ratings](https://docs.trakt.tv/reference/getusersratingsall.md): #### 🔓 OAuth Optional ✨ Extended Info Returns all ratings by a user including each rating value and when it was rated. - [Get data syncs](https://docs.trakt.tv/reference/getuserssyncslist.md): #### 🔒 OAuth Required 📄 Pagination Paginated list of the authenticated user's data syncs across **every** connected app (younify, plex, importers). Counts only — the paused/skipped item arrays are served by the dedicated paginated endpoints. Pagination is via `page` / `limit` and the standard `X-Pagination-*` headers. `X-Pagination-Item-Count` is the total sync count (use it for the "Data has synced N times" banner). All timestamps are normalized to `.000Z`. - [Get data syncs by type](https://docs.trakt.tv/reference/getuserssyncslistbytype.md): #### 🔒 OAuth Required 📄 Pagination Same as the list of data syncs, filtered by the app that created them. The `type` matches the `kind` returned on each row (`younify`, `plex`, or `import` for anything else, including `application_id 0` importers). An unknown `type` returns `404` rather than silently returning everything. Pagination and `X-Pagination-*` headers are identical to the unfiltered list. - [Get a data sync](https://docs.trakt.tv/reference/getuserssyncsdetails.md): #### 🔒 OAuth Required Returns a single sync scoped to the authenticated user — foreign ids return `404`. Same shape as a list row: added counts plus `paused_count` / `skipped_count`, no item arrays. A numeric segment (`/users/syncs/157`) hits this endpoint; a non-numeric segment (`/users/syncs/younify`) is the filtered list. - [Undo a data sync](https://docs.trakt.tv/reference/deleteuserssyncsundo.md): #### 🔒 OAuth Required Undoes a sync — reverses every item it imported (history, ratings, paused, watchlist, collection) and marks it undone. Scoped to the authenticated user; a foreign sync returns `404`. - [Get paused sync items](https://docs.trakt.tv/reference/getuserssyncspaused.md): #### 🔒 OAuth Required 📄 Pagination Paginated item array for a sync, scoped to the authenticated user — foreign ids return `404`. Split out because a single sync can hold thousands of items. Paused items are always `history` (their `kind` is always `"history"`). Each item is the raw stored item (so source-specific fields are preserved) plus a normalized envelope, with timestamps normalized to `.000Z`. Pagination and `X-Pagination-*` headers are identical to the list endpoint. - [Get skipped sync items](https://docs.trakt.tv/reference/getuserssyncsskipped.md): #### 🔒 OAuth Required 📄 Pagination Paginated item array for a sync, scoped to the authenticated user — foreign ids return `404`. Split out because a single sync can hold thousands of items. Skipped items mix `history` and `rating` (see each item's `kind` discriminator). Each item is the raw stored item (so source-specific fields are preserved) plus a normalized envelope, with timestamps normalized to `.000Z`. Pagination and `X-Pagination-*` headers are identical to the list endpoint. - [Get Plex settings](https://docs.trakt.tv/reference/getusersplexsettings.md): #### 🔒 OAuth Required Returns the authenticated user's Plex connection status, real-time scrobbler webhook info, server/library/home-user selection, and both toggle sets (batch `sync` + real-time `scrobbler`). Read-only, though the VIP webhook URL lazily mints its tokens. `connection.connected` reflects that a Plex authorization exists; for a live auth check call `servers` and watch for a `bad_auth` error. `webhook.url` is null unless the user is VIP. `sync.configured` indicates the initial sync has been set up. Toggles are booleans (unset ⇒ `false`); sync toggles include `watching`/`watchlist`, scrobbler toggles do not carry `watchlist`. All timestamps are normalized to `.000Z`. - [Update Plex settings](https://docs.trakt.tv/reference/putusersplexupdatesettings.md): #### 🔒 OAuth Required Writes the Plex toggles, selection, and home users. Mirrors the GET shape so it round-trips; omitted toggle keys are left unchanged (no clobbering), and `library_ids` is sent structured and rebuilt into the `server|uuid` storage server-side. The optional `trigger_sync` block is the only thing that touches sync timestamps or enqueues work: any `*_all_data: true` resets the affected cursors and enqueues a full sync per selected server; present-but-all-false seeds every cursor to "now" (the first sync skips old history); absent writes settings without syncing. - [Connect Plex](https://docs.trakt.tv/reference/postusersplexconnect.md): #### 🔒 OAuth Required Mints a Plex web-auth URL for the client to open. Plex uses a 2-step PIN OAuth; the PIN is stashed server-side under an opaque `state` token and Plex is forwarded to a website return endpoint that exchanges it and redirects back to your `return_url` with `?plex_status=connected|error`. `return_url` is validated against the trakt-owned allowlist (`trakt://`, `http(s)://localhost`, `https://*.trakt.tv`); a `400` is returned otherwise. - [Disconnect Plex](https://docs.trakt.tv/reference/deleteusersplexdisconnect.md): #### 🔒 OAuth Required Disconnects Plex: destroys the authorization, clears server/library/user selection and sync state, and busts the connection caches. - [Get Plex servers](https://docs.trakt.tv/reference/getusersplexservers.md): #### 🔒 OAuth Required Lists the authenticated user's Plex servers. Network-bound — probes each server's remote URL. On a Plex/auth failure it returns the shared `{ error_code, message, guidance }` envelope: `bad_auth` (401), `plex_timeout` (504), `plex_bad_response`/`plex_generic_error` (502). - [Get Plex server accounts and libraries](https://docs.trakt.tv/reference/getusersplexserveraccounts.md): #### 🔒 OAuth Required Returns the home accounts (owned servers only) and syncable libraries for a Plex server, with the user's current library selection flagged. Network-bound. Errors use the shared `{ error_code, message, guidance }` envelope: `missing_token`/`bad_auth` (401), `missing_server_id`/`plex_unprocessable` (422), `invalid_server_id`/`plex_not_found` (404), `invalid_server_url` (503), `plex_timeout` (504), `plex_bad_response`/`plex_generic_error` (502). - [Sync Plex now](https://docs.trakt.tv/reference/postusersplexsync.md): #### 🔒 OAuth Required Enqueues a Plex sync immediately. With `server_id`, syncs that server; without it, syncs every server in the saved selection. `all_data: true` re-pulls full history, otherwise an incremental sync. A `422` is returned when there is no server to sync. - [Get likes](https://docs.trakt.tv/reference/getuserslikes.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns likes for a user filtered by type. - [Get collection](https://docs.trakt.tv/reference/getuserscollection.md): #### 🔓 OAuth Optional ✨ Extended Info Returns collection items for a user filtered by type. - [Get notes](https://docs.trakt.tv/reference/getusersnotes.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 😁 Emojis Returns notes for a user filtered by type. - [Get watched](https://docs.trakt.tv/reference/getuserswatchedtyped.md): #### 🔓 OAuth Optional ✨ Extended Info Returns all movies or shows a user has watched sorted by most recently watched. - [Get watched history](https://docs.trakt.tv/reference/getusershistorytypeditem.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns watched history entries for one item. Use `type`, `item_id`, `start_at`, and `end_at` to limit the result set. - [Get watchlist](https://docs.trakt.tv/reference/getuserswatchlisttypedsorted.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns all items in a user's watchlist filtered by type. - [Get ratings](https://docs.trakt.tv/reference/getusersratingstypedrating.md): Returns ratings by a user for the requested media type and rating value. - [Get favorites](https://docs.trakt.tv/reference/getusersfavoritestypedsorted.md): #### 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis Returns the top 100 shows and movies a user has favorited. - [Get items on a personal list](https://docs.trakt.tv/reference/getuserslistslistitemstypedsorted.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters Returns items on a personal list. Use `type`, `sort_by`, and `sort_how` to control the returned item set and order. - [Reorder items on a list](https://docs.trakt.tv/reference/postuserslistslistreorderitems.md): #### 🔒 OAuth Required Reorder items on a personal list. Send the ordered list item IDs in the request body; the response returns the updated item order. - [Update a list item](https://docs.trakt.tv/reference/putuserslistslistupdateitem.md): Update a single personal list item by list item ID. A successful update returns no response body. - [Like a list](https://docs.trakt.tv/reference/postuserslistslistlike.md): #### 🔒 OAuth Required Votes help determine popular lists. Only one like is allowed per list per user. - [Remove like on a list](https://docs.trakt.tv/reference/deleteuserslistslistunlike.md): #### 🔒 OAuth Required Remove a like on a list. - [Report a user's list](https://docs.trakt.tv/reference/postuserslistslistreport.md): #### 🔒 OAuth Required Report a list for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per list. - [Get hidden items](https://docs.trakt.tv/reference/getusershiddengetbysection.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns hidden items for a specific section. Use `type`, `page`, and `limit` to filter and paginate the hidden items. - [Remove hidden items](https://docs.trakt.tv/reference/postusershiddenremovesection.md): #### 🔒 OAuth Required Remove hidden items for a specific section. Send hideable media objects in the request body; the response contains remove counts. - [Get a user's smart lists](https://docs.trakt.tv/reference/getuserssmartlistspersonal.md): #### 🔓 OAuth Optional Returns all smart list definitions for a user. Use the [**/users/:id/smart-lists/:list_id/items**](#reference/users) method to get the dynamic items a specific smart list resolves to. - [Create smart list](https://docs.trakt.tv/reference/postuserssmartlistscreate.md): #### 🔥 VIP Enhanced 🔒 OAuth Required Create a new smart list. A smart list is a dynamic list driven by a `source` and `filters` rather than manually added items. #### JSON POST Data | Key | Type | Value | |---|---|---| | `name` * | string | Name of the smart list. | | `source` * | string | `trending`, `popular`, `anticipated`, `recommendations`, `discover`, `watchlist`, `library` | | `media_type` * | string | `movies`, `shows`, `media` | | `filters` | object | Filter constraints applied to the source. | | `privacy` | string | `public`, `private`, `friends` | - [Get smart list](https://docs.trakt.tv/reference/getuserssmartlistssmartlistsummary.md): #### 🔓 OAuth Optional Returns a single smart list definition. Use the [**/users/:id/smart-lists/:list_id/items**](#reference/users) method to get the dynamic items this smart list resolves to. - [Update smart list](https://docs.trakt.tv/reference/putuserssmartlistssmartlistupdate.md): #### 🔒 OAuth Required Update a smart list by sending 1 or more parameters. The `source`, `media_type`, `filters`, and `privacy` can all be changed; the slug is retained so existing references keep working. - [Delete a user's smart list](https://docs.trakt.tv/reference/deleteuserssmartlistssmartlistdelete.md): #### 🔒 OAuth Required Remove a smart list. - [Get trending lists](https://docs.trakt.tv/reference/getliststrending.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns trending lists ordered by current activity. Use pagination and filters to control the result set. - [Get popular lists](https://docs.trakt.tv/reference/getlistspopular.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns popular lists ordered by long-term activity. Use pagination and filters to control the result set. - [Get list](https://docs.trakt.tv/reference/getlistssummary.md): #### 😁 Emojis Returns a single list. Use the [**/lists/:id/items**](#reference/lists/list-items) method to get the actual items this list contains. > ### Note > _You must use an integer `id`, and only public lists will return data._ - [Get all users who liked a list](https://docs.trakt.tv/reference/getlistslikes.md): #### 📄 Pagination Returns all users who liked a list. - [Like a list](https://docs.trakt.tv/reference/postlistslike.md): #### 🔒 OAuth Required Votes help determine popular lists. Only one like is allowed per list per user. - [Remove like on a list](https://docs.trakt.tv/reference/deletelistsunlike.md): #### 🔒 OAuth Required Remove a like on a list. - [Get movie list items](https://docs.trakt.tv/reference/getlistsitemsmovie.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns movie items on a public list. Use `id` to identify the list and query sorting, filters, and pagination to control the result set. - [Get show list items](https://docs.trakt.tv/reference/getlistsitemsshow.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns show items on a public list. Use `id` to identify the list and query sorting, filters, and pagination to control the result set. - [Get all list items](https://docs.trakt.tv/reference/getlistsitemsall.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns movie, show, episode, and season items on a public list. Use `id` to identify the list and query sorting, filters, and pagination to control the result set. - [Get media list items](https://docs.trakt.tv/reference/getlistsitemsmedia.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns movie and show items on a public list. Use `id` to identify the list and query sorting, filters, and pagination to control the result set. - [Report a list](https://docs.trakt.tv/reference/postlistsreport.md): #### 🔒 OAuth Required Report a list for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per list. | reason | description | |---|---| | `duplicate` | Duplicate of another list | | `remove` | Should be removed from Trakt | | `metadata` | Metadata is wrong (name, description, etc) | | `adult` | Contains adult content | | `language` | Not in English | | `spam` | Spam or self-promotion | | `other` | Anything else (add details in `message`) | - [Get trending lists](https://docs.trakt.tv/reference/getliststrendingbytype.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns trending lists ordered by current activity. Use `type`, pagination, and filters to control the result set. - [Get popular lists](https://docs.trakt.tv/reference/getlistspopularbytype.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns popular lists ordered by long-term activity. Use `type`, pagination, and filters to control the result set. - [Get items on a list](https://docs.trakt.tv/reference/getlistsitemstypedsorted.md): #### 🔥 VIP Enhanced 📄 Pagination Optional ✨ Extended Info 😁 Emojis Get all items on a personal list. Items can be a `movie`, `show`, `season`, `episode`, or `person`. You can optionally specify the `type` parameter with a single value or comma delimited string for multiple item types. - [Get all list comments](https://docs.trakt.tv/reference/getlistscomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for a list. By default, comments are sorted by most `likes`. Other sorting options include `likes_30`, most `replies`, `replies_30`, most `plays`, highest `rating`, and `added` date. > ### Note > _If you send OAuth, comments from blocked users will be automatically filtered out._ - [Add items to watched history](https://docs.trakt.tv/reference/postsynchistoryadd.md): #### 🔒 OAuth Required Add items to a user's watch history. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be added. If seasons are specified, only episodes in those seasons will be added. Send a `watched_at` UTC datetime to mark items as watched in the past. This is useful for syncing past watches from a media center. > ### IMPORTANT > _Please be careful with sending duplicate data. We don't verify the `item` + `watched_at` to ensure it's unique, it is up to your app to veify this and not send duplicate plays._ #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | #### Media Object POST Data | Key | Type | Value | |---|---|---| | item * | object | `movie`, `show`, or `episode` object. | | `watched_at` | datetime | UTC datetime when the item was watched. Set to `released` to automatically use the initial release date + runtime *(episodes only)*. Set to `unknown` to mark the item as watched without a specific date. | - [Remove items from history](https://docs.trakt.tv/reference/postsynchistoryremove.md): #### 🔒 OAuth Required Remove items from a user's watch history including all watches, scrobbles, and checkins. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be removed. If seasons are specified, only episodes in those seasons will be removed. You can also send a list of raw history `ids` _(64-bit integers)_ to delete single plays from the watched history. The [**/sync/history**](#reference/sync/get-history) method will return an individual `id` _(64-bit integer)_ for each history item. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | | `ids` | array | Array of history ids. | - [Get up next](https://docs.trakt.tv/reference/getsyncprogressupnextstandard.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns the authenticated user up next progress ordered by the requested sort. Use `include_stats` and `lifetime_stats` to include additional watch stats. - [Get up next nitro](https://docs.trakt.tv/reference/getsyncprogressupnextnitro.md): #### 🔒 OAuth Required 📄 Pagination Returns the authenticated user up next progress optimized for intent-based clients. Use `intent` plus sorting and pagination to control the response. - [Add items to watchlist](https://docs.trakt.tv/reference/postsyncwatchlistadd.md): #### 🔥 VIP Enhanced 🔒 OAuth Required 😁 Emojis Add one of more items to a user's watchlist. Accepts shows, seasons, episodes and movies. If only a show is passed, only the show itself will be added. If seasons are specified, all of those seasons will be added. #### Notes Each watchlist item can optionally accept a `notes` *(500 maximum characters)* field with custom text. The user must be a [**Trakt VIP**](https://trakt.tv/vip) to send `notes`. #### Limits If the user's watchlist limit is exceeded, a `420` HTTP error code is returned. Use the [**/users/settings**](/reference/users/settings) method to get all limits for a user account. In most cases, upgrading to [**Trakt VIP**](https://trakt.tv/vip) will increase the limits. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | - [Remove items from watchlist](https://docs.trakt.tv/reference/postsyncwatchlistremove.md): #### 🔒 OAuth Required Remove one or more items from a user's watchlist. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | - [Add new ratings](https://docs.trakt.tv/reference/postsyncratingsadd.md): #### 🔒 OAuth Required Rate one or more items. Accepts shows, seasons, episodes and movies. If only a show is passed, only the show itself will be rated. If seasons are specified, all of those seasons will be rated. Send a `rated_at` UTC datetime to mark items as rated in the past. This is useful for syncing ratings from a media center. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | #### Media Object POST Data | Key | Type | Value | |---|---|---| | item * | object | `movie`, `show`, `season`, or `episode` object. | | `rating` * | integer | Between 1 and 10. | | `rated_at` | datetime | UTC datetime when the item was rated. | - [Add items to favorites](https://docs.trakt.tv/reference/postsyncfavoritesadd.md): #### 🔒 OAuth Required 😁 Emojis If the user only had 50 TV shows and movies to bring with them on a deserted island, what would they be? Apps should encourage user's to add favorites so the algorithm keeps getting better. #### Notes Each favorite can optionally accept a `notes` *(500 maximum characters)* field explaining why the user favorited the item. #### Limits If the user's favorite limit is exceeded, a `420` HTTP error code is returned. This limit applies to all users. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | - [Remove items from favorites](https://docs.trakt.tv/reference/postsyncfavoritesremove.md): #### 🔒 OAuth Required Remove items from a user's favorites. Apps should encourage user's to add favorites so the algorithm keeps getting better. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | - [Get minimal movie collection](https://docs.trakt.tv/reference/getsynccollectionminimalmovies.md): #### 🔒 OAuth Required Returns the authenticated user movie collection in a minimal format optimized for syncing local state. - [Get minimal show collection](https://docs.trakt.tv/reference/getsynccollectionminimalshows.md): #### 🔒 OAuth Required Returns the authenticated user show collection in a minimal format optimized for syncing local state. - [Get minimal episode collection](https://docs.trakt.tv/reference/getsynccollectionminimalepisodes.md): #### 🔒 OAuth Required Returns the authenticated user episode collection in a minimal format optimized for syncing local state. - [Get movie playback progress](https://docs.trakt.tv/reference/getsyncprogressmovies.md): #### 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info Returns in-progress movie playback items for the authenticated user. Use `start_at` and `end_at` to filter progress updated within a UTC datetime range. - [Remove a playback item](https://docs.trakt.tv/reference/deletesyncprogressdropmovie.md): #### 🔒 OAuth Required Remove a playback item from a user's playback progress list. A `404` will be returned if the `id` is invalid. - [Remove ratings](https://docs.trakt.tv/reference/postsyncratingsremove.md): #### 🔒 OAuth Required Remove ratings for one or more items. #### JSON POST Data | Key | Type | Value | |---|---|---| | `movies` | array | Array of `movie` objects. (see examples ->) | | `shows` | array | Array of `show` objects. | | `seasons` | array | Array of `season` objects. | | `episodes` | array | Array of `episode` objects. | - [Get movie collection](https://docs.trakt.tv/reference/getsynccollectionmovies.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns movies in the authenticated user collection. Use `available_on` and pagination to filter and move through collected movies. - [Get show collection](https://docs.trakt.tv/reference/getsynccollectionshows.md): #### 🔒 OAuth Required ✨ Extended Info Returns shows in the authenticated user collection, including collected seasons and episodes. - [Get episode collection](https://docs.trakt.tv/reference/getsynccollectionepisodes.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns episodes in the authenticated user collection. Use `available_on` and pagination to filter and move through collected episodes. - [Get media collection](https://docs.trakt.tv/reference/getsynccollectionmedia.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns movies, shows, and episodes in the authenticated user collection. Use `available_on` and pagination to filter and move through collected media. - [Get watched progress](https://docs.trakt.tv/reference/getsyncprogresswatched.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns watched progress for the authenticated user. Use hide filters to include or exclude completed, incomplete, or currently rewatching shows. - [Get last activity](https://docs.trakt.tv/reference/getsynclastactivities.md): #### 🔒 OAuth Required Returns the latest activity timestamps for the authenticated user. Cache these dates locally and compare them before syncing to avoid fetching data that has not changed. - [Get watched history](https://docs.trakt.tv/reference/getsynchistoryget.md): #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns movies and episodes that a user has watched, sorted by most recent. Specify a `type` and Trakt `id` to limit the history for just that item. - [Get playback progress](https://docs.trakt.tv/reference/getsyncprogressplayback.md): #### 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info Returns playback progress for the requested media `type`. Use `start_at` and `end_at` to filter progress updated within a UTC datetime range. - [Get watched](https://docs.trakt.tv/reference/getsyncwatched.md): Returns all movies, shows, seasons, or episodes watched by the authenticated user. - [Get watchlist](https://docs.trakt.tv/reference/getsyncwatchlistget.md): #### 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis Returns all items in the authenticated user's watchlist filtered by type. - [Update watchlist](https://docs.trakt.tv/reference/putsyncwatchlistupdate.md): Update watchlist item metadata such as notes or rank for multiple items. - [Reorder watchlist items](https://docs.trakt.tv/reference/postsyncwatchlistreorder.md): Reorder all items in a user watchlist by sending the ordered list item IDs. - [Update a watchlist item](https://docs.trakt.tv/reference/putsyncwatchlistupdateitem.md): Update a single watchlist item by list item ID. A successful update returns no response body. - [Get ratings](https://docs.trakt.tv/reference/getsyncratingsget.md): Returns all ratings for the requested media type and rating value. - [Get favorites](https://docs.trakt.tv/reference/getsyncfavoritesget.md): #### 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis Returns all items in the authenticated user's favorites filtered by type. - [Update favorites](https://docs.trakt.tv/reference/putsyncfavoritesupdate.md): Update favorite item metadata such as notes or rank for multiple items. - [Reorder favorited items](https://docs.trakt.tv/reference/postsyncfavoritesreorder.md): Reorder all items in a user favorites list by sending the ordered list item IDs. - [Update a favorite item](https://docs.trakt.tv/reference/putsyncfavoritesupdateitem.md): Update a single favorite item by list item ID. A successful update returns no response body. - [Get collection](https://docs.trakt.tv/reference/getsynccollectionall.md): #### 🔒 OAuth Required ✨ Extended Info Returns all collected items for a media `type`. - [Add items to collection](https://docs.trakt.tv/reference/postsynccollectionadd.md): Add items to a user collection. Accepts shows, seasons, episodes, and movies. - [Remove items from collection](https://docs.trakt.tv/reference/postsynccollectionremove.md): Remove items from a user collection. Accepts shows, seasons, episodes, and movies. - [Get movie recommendations](https://docs.trakt.tv/reference/getrecommendationsmoviesrecommend.md): #### 🔒 OAuth Required ✨ Extended Info Movie recommendations for a user. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. Set `ignore_collected=true` to filter out movies the user has already collected or `ignore_watchlisted=true` to filter out movies the user has already watchlisted. The `favorited_by` array contains all users who favorited the item along with any notes they added. - [Hide a movie recommendation](https://docs.trakt.tv/reference/deleterecommendationsmovieshide.md): #### 🔒 OAuth Required Hide a movie from getting recommended anymore. - [Get show recommendations](https://docs.trakt.tv/reference/getrecommendationsshowsrecommend.md): #### 🔒 OAuth Required ✨ Extended Info TV show recommendations for a user. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. Set `ignore_collected=true` to filter out shows the user has already collected or `ignore_watchlisted=true` to filter out shows the user has already watchlisted. The `favorited_by` array contains all users who favorited the item along with any notes they added. - [Hide a show recommendation](https://docs.trakt.tv/reference/deleterecommendationsshowshide.md): #### 🔒 OAuth Required Hide a show from getting recommended anymore. - [Get a movie](https://docs.trakt.tv/reference/getmoviessummary.md): #### ✨ Extended Info Returns a single movie's details. > ### Note > _When getting `full` extended info, the `status` field can have a value of `released`, `in production`, `post production`, `planned`, `rumored`, or `canceled`._ - [Get movie ratings](https://docs.trakt.tv/reference/getmoviesratings.md): Returns the Trakt rating (between 0 and 10), vote count, and rating distribution for a movie. Use `?extended=all` to include ratings from TMDB, IMDb, Metascore, Rotten Tomatoes, Letterboxd, and MyAnimeList. External ratings, vote counts, and links can be `null` when unavailable. - [Get movie stats](https://docs.trakt.tv/reference/getmoviesstats.md): Returns lots of movie stats. - [Get all movie translations](https://docs.trakt.tv/reference/getmoviestranslations.md): Returns all translations for a movie, including language, country, and translated values for title, tagline and overview. The `country` field can be used together with `language` to identify regional variants (for example `fr`/`fr` vs `fr`/`ca`). - [Get related movies](https://docs.trakt.tv/reference/getmoviesrelated.md): #### 📄 Pagination ✨ Extended Info Returns related and similar movies. - [Get users watching right now](https://docs.trakt.tv/reference/getmovieswatching.md): #### ✨ Extended Info Returns all users watching this movie right now. - [Get movie studios](https://docs.trakt.tv/reference/getmoviesstudios.md): Returns all studios for a movie. - [Get movie watch now sources](https://docs.trakt.tv/reference/getmovieswatchnow.md): #### 🫣 Limited Access ✨ Extended Info This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns streaming and watch now sources for a movie in the requested country. Use `links` to include provider links when available. - [Get all people for a movie](https://docs.trakt.tv/reference/getmoviespeople.md): #### ✨ Extended Info Returns all `cast` and `crew` for a movie. Each `cast` member will have a `characters` array and a standard `person` object. The `crew` object will be broken up by department into `production`, `art`, `crew`, `costume & make-up`, `directing`, `writing`, `sound`, `camera`, `visual effects`, `lighting`, and `editing` (if there are people for those crew positions). Each of those members will have a `jobs` array and a standard `person` object. - [Get all videos](https://docs.trakt.tv/reference/getmoviesvideos.md): #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. - [Get lists containing this movie](https://docs.trakt.tv/reference/getmovieslists.md): #### 📄 Pagination 😁 Emojis Returns all lists that contain this movie. By default, `personal` lists are returned sorted by the most `popular`. - [Get all movie comments](https://docs.trakt.tv/reference/getmoviescomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for a movie. By default, comments are sorted by most `likes`. Other sorting options include `likes_30`, most `replies`, `replies_30`, most `plays`, highest `rating`, and `added` date. > ### Note > _If you send OAuth, comments from blocked users will be automatically filtered out._ - [Get movie sentiments](https://docs.trakt.tv/reference/getmoviessentiments.md): Returns sentiment counts for comments and reactions attached to a movie. - [Get trending movies](https://docs.trakt.tv/reference/getmoviestrending.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most watched movies over the last 24 hours. Movies with the most `watchers` are returned first. - [Get the most watched movies](https://docs.trakt.tv/reference/getmovieswatched.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most watched (unique users) movies in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. - [Get the most anticipated movies](https://docs.trakt.tv/reference/getmoviesanticipated.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most anticipated movies based on the number of lists a movie appears on. - [Get popular movies](https://docs.trakt.tv/reference/getmoviespopular.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most popular movies. Popularity is calculated using the rating percentage and the number of ratings. - [Get streaming movies](https://docs.trakt.tv/reference/getmoviesstreaming.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns movies recently available on streaming services for the requested `period`. Results can be filtered by media fields or ignored user state. - [Get hot movies](https://docs.trakt.tv/reference/getmovieshot.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns movies that are currently hot on Trakt. Results can be filtered by media fields or ignored user state. - [Get movie JustWatch links](https://docs.trakt.tv/reference/getmoviesjustwatchlink.md): #### 🫣 Limited Access This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns JustWatch links for a movie in the requested country. Use the movie `id` and two-character `country` path parameter to identify the lookup. - [Report a movie](https://docs.trakt.tv/reference/postmoviesreport.md): #### 🔒 OAuth Required Report a movie for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per movie. | reason | description | |---|---| | `duplicate` | Duplicate of another movie on Trakt | | `remove` | Should be removed from Trakt | | `data_refresh` | Request a full metadata refresh | | `metadata` | Metadata is wrong (title, overview, etc) | | `adult` | Marked as adult when it shouldn't be (or vice versa) | | `runtime` | Runtime is incorrect | | `language` | Not in English | | `spam` | Spam or fake title | | `tmdb` | Should use TMDB as the datasource | | `other` | Anything else (add details in `message`) | - [Refresh movie JustWatch links](https://docs.trakt.tv/reference/postmoviesjustwatchrefresh.md): #### 🔥 VIP Only 🔒 OAuth Required Queue a refresh of a movie's JustWatch watch now links. - [Refresh movie metadata](https://docs.trakt.tv/reference/postmoviesrefresh.md): #### 🔥 VIP Only 🔒 OAuth Required Queue a full metadata refresh for a movie. Pass `images=true` to also refresh the movie's images. - [Get all movie aliases](https://docs.trakt.tv/reference/getmoviesaliases.md): Returns all title aliases for a movie. Includes localized and alternate titles when available. - [Get all movie releases](https://docs.trakt.tv/reference/getmoviesreleases.md): Returns release dates for a movie in the requested country, including certification and release type when available. - [Get the most favorited movies](https://docs.trakt.tv/reference/getmoviesfavorited.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most favorited movies in the specified time `period`, defaulting to `weekly`. - [Get the most played movies](https://docs.trakt.tv/reference/getmoviesplayed.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most played movies in the specified time `period`, defaulting to `weekly`. - [Get the most collected movies](https://docs.trakt.tv/reference/getmoviescollected.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most collected movies in the specified time `period`, defaulting to `weekly`. - [Get the weekend box office](https://docs.trakt.tv/reference/getmoviesboxoffice.md): Returns the top 10 grossing movies in the U.S. box office last weekend. Updated every Monday morning. - [Get recently updated movies](https://docs.trakt.tv/reference/getmoviesupdates.md): Returns all movies updated since the specified UTC date. We recommend storing the latest `updated_at` locally and using it for the next request. - [Get recently updated movie Trakt IDs](https://docs.trakt.tv/reference/getmoviesupdatedids.md): Returns Trakt IDs for movies updated since the specified UTC date. - [Get a single show](https://docs.trakt.tv/reference/getshowssummary.md): #### ✨ Extended Info Returns a single shows's details. If you request extended info, the `airs` object is relative to the show's country. You can use the `day`, `time`, and `timezone` to construct your own date then convert it to whatever timezone your user is in. > ### Note > _When getting `full` extended info, the `status` field can have a value of `returning series` (airing right now), `continuing` (airing right now), `in production` (airing soon), `planned` (in development), `upcoming` (in development), `pilot`, `canceled`, or `ended`._ - [Get show ratings](https://docs.trakt.tv/reference/getshowsratings.md): Returns the Trakt rating (between 0 and 10), vote count, and rating distribution for a show. Use `?extended=all` to include ratings from TMDB, IMDb, Metascore, Rotten Tomatoes, and MyAnimeList. External ratings, vote counts, and links can be `null` when unavailable. - [Get show stats](https://docs.trakt.tv/reference/getshowsstats.md): Returns lots of show stats. - [Get show watched progress](https://docs.trakt.tv/reference/getshowsprogresswatched.md): #### 🔒 OAuth Required Returns watched progress for a show including details on all aired seasons and episodes. The `next_episode` will be the next episode the user should watch, if there are no upcoming episodes it will be set to `null`. If not `null`, the `reset_at` date is when the user started re-watching the show. Your app can adjust the progress by ignoring episodes with a `last_watched_at` prior to the `reset_at`. By default, any hidden seasons will be removed from the response and stats. To include these and adjust the completion stats, set the `hidden` flag to `true`. By default, specials will be excluded from the response. Set the `specials` flag to `true` to include season 0 and adjust the stats accordingly. If you'd like to include specials, but not adjust the stats, set `count_specials` to `false`. By default, the `last_episode` and `next_episode` are calculated using the last `aired` episode the user has watched, even if they've watched older episodes more recently. To use their last watched episode for these calculations, set the `last_activity` flag to `watched`. > ### Note > _Only aired episodes are used to calculate progress. Episodes in the future or without an air date are ignored._ - [Get all show translations](https://docs.trakt.tv/reference/getshowstranslations.md): Returns all translations for a show, including language, country, and translated values for title, tagline and overview. The `country` field can be used together with `language` to identify regional variants (for example `fr`/`fr` vs `fr`/`ca`). - [Get related shows](https://docs.trakt.tv/reference/getshowsrelated.md): #### 📄 Pagination ✨ Extended Info Returns related and similar shows. - [Get users watching right now](https://docs.trakt.tv/reference/getshowswatching.md): #### ✨ Extended Info Returns all users watching this show right now. - [Get show studios](https://docs.trakt.tv/reference/getshowsstudios.md): Returns all studios for a show. - [Get show watch now sources](https://docs.trakt.tv/reference/getshowswatchnow.md): #### 🫣 Limited Access ✨ Extended Info This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns streaming and watch now sources for a show in the requested country. Use `links` to include provider links when available. - [Get all people for a show](https://docs.trakt.tv/reference/getshowspeople.md): #### ✨ Extended Info Returns all `cast` and `crew` for a show, including the `episode_count` for which they appears. Each `cast` member will have a `characters` array and a standard `person` object. The `crew` object will be broken up by department into `production`, `art`, `crew`, `costume & make-up`, `directing`, `writing`, `sound`, `camera`, `visual effects`, `lighting`, `editing`, and `created by` (if there are people for those crew positions). Each of those members will have a `jobs` array and a standard `person` object. #### Guest Stars If you add `?extended=guest_stars` to the URL, it will return all guest stars that appeared in at least 1 episode of the show. > ### Note > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ - [Get all seasons for a show](https://docs.trakt.tv/reference/getshowsseasons.md): #### ✨ Extended Info Returns all seasons for a show including the number of episodes in each season. #### Episodes If you add `?extended=episodes` to the URL, it will return all episodes for all seasons. > ### Note > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ - [Get all episodes for a single season](https://docs.trakt.tv/reference/getshowsseasonepisodes.md): #### ✨ Extended Info Returns all episodes for a specific season of a show. #### Translations If you'd like to included translated episode titles and overviews in the response, include the `translations` parameter in the URL. Include all languages by setting the parameter to `all` or use a specific 2 digit country language code to further limit it. Each translation includes both `language` and `country` so regional variants (for example `fr`/`fr` vs `fr`/`ca`) can be distinguished. > ### Note > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ - [Get all videos](https://docs.trakt.tv/reference/getshowsseasonvideos.md): #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. - [Get all videos](https://docs.trakt.tv/reference/getshowsvideos.md): #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. - [Get lists containing this show](https://docs.trakt.tv/reference/getshowslists.md): #### 📄 Pagination 😁 Emojis Returns all lists that contain this show. By default, `personal` lists are returned sorted by the most `popular`. - [Get all show comments](https://docs.trakt.tv/reference/getshowscomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for a show. By default, comments are sorted by most `likes`. Other sorting options include `likes_30`, most `replies`, `replies_30`, highest `watched` percentage, most `plays`, highest `rating`, and `added` date. > ### Note > _If you send OAuth, comments from blocked users will be automatically filtered out._ - [Get show sentiments](https://docs.trakt.tv/reference/getshowssentiments.md): Returns sentiment counts for comments and reactions attached to a show. - [Get a single episode for a show](https://docs.trakt.tv/reference/getshowsepisodesummary.md): #### ✨ Extended Info Returns a single episode's details. All date and times are in UTC and were calculated using the episode's `air_date` and show's `country` and `air_time`. > ### Note > _If the `first_aired` is unknown, it will be set to `null`._ > ### Note > _When getting `full` extended info, the `episode_type` field can have a value of `standard`, `series_premiere` (season 1, episode 1), `season_premiere` (episode 1), `mid_season_finale`, `mid_season_premiere` (the next episode after the mid season finale), `season_finale`, or `series_finale` (last episode to air for an ended show)._ - [Get all episode translations](https://docs.trakt.tv/reference/getshowsepisodetranslations.md): Returns all translations for an episode, including language, country, and translated values for title and overview. The `country` field can be used together with `language` to identify regional variants (for example `fr`/`fr` vs `fr`/`ca`). - [Get episode stats](https://docs.trakt.tv/reference/getshowsepisodestats.md): Returns lots of episode stats. - [Get episode ratings](https://docs.trakt.tv/reference/getshowsepisoderatings.md): Returns the Trakt rating (between 0 and 10), vote count, and rating distribution for an episode. Use `?extended=all` to include ratings from TMDB, IMDb, Metascore, and Rotten Tomatoes. External ratings, vote counts, and links can be `null` when unavailable. - [Get users watching right now](https://docs.trakt.tv/reference/getshowsepisodewatching.md): #### ✨ Extended Info Returns all users watching this episode right now. - [Get all episode comments](https://docs.trakt.tv/reference/getshowsepisodecomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for an episode. By default, comments are sorted by most `likes`. Other sorting options include `likes_30`, most `replies`, `replies_30`, most `plays`, highest `rating`, and `added` date. > ### Note > _If you send OAuth, comments from blocked users will be automatically filtered out._ - [Get all people for an episode](https://docs.trakt.tv/reference/getshowsepisodepeople.md): #### ✨ Extended Info Returns all `cast` and `crew` for an episode. Each `cast` member will have a `characters` array and a standard `person` object. The `crew` object will be broken up by department into `production`, `art`, `crew`, `costume & make-up`, `directing`, `writing`, `sound`, `camera`, `visual effects`, `lighting`, and `editing` (if there are people for those crew positions). Each of those members will have a `jobs` array and a standard `person` object. #### Guest Stars If you add `?extended=guest_stars` to the URL, it will return all guest stars that appeared in the episode. > ### Note > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ - [Get episode watch now sources](https://docs.trakt.tv/reference/getshowsepisodewatchnow.md): #### 🫣 Limited Access ✨ Extended Info This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns streaming and watch now sources for an episode in the requested country. Use `links` to include provider links when available. - [Get trending shows](https://docs.trakt.tv/reference/getshowstrending.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most watched shows over the last 24 hours. Shows with the most `watchers` are returned first. - [Get the most watched shows](https://docs.trakt.tv/reference/getshowswatched.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most watched (unique users) shows in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. - [Get the most anticipated shows](https://docs.trakt.tv/reference/getshowsanticipated.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most anticipated shows based on the number of lists a show appears on. - [Get popular shows](https://docs.trakt.tv/reference/getshowspopular.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most popular shows. Popularity is calculated using the rating percentage and the number of ratings. - [Get streaming shows](https://docs.trakt.tv/reference/getshowsstreaming.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns shows recently available on streaming services for the requested `period`. Results can be filtered by media fields or ignored user state. - [Get hot shows](https://docs.trakt.tv/reference/getshowshot.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns shows that are currently hot on Trakt. Results can be filtered by media fields or ignored user state. - [Get show JustWatch links](https://docs.trakt.tv/reference/getshowsjustwatchlink.md): #### 🫣 Limited Access This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns JustWatch links for a show in the requested country. Use the show `id` and two-character `country` path parameter to identify the lookup. - [Get season JustWatch links](https://docs.trakt.tv/reference/getshowsseasonjustwatchlink.md): #### 🫣 Limited Access This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns JustWatch links for a show season in the requested country. Use `id`, `season`, and the two-character `country` path parameter to identify the lookup. - [Report a season](https://docs.trakt.tv/reference/postshowsseasonreport.md): #### 🔒 OAuth Required Report a season for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per season. | reason | description | |---|---| | `duplicate` | Duplicate of another season on Trakt | | `remove` | Should be removed from Trakt | | `data_refresh` | Request a full metadata refresh | | `metadata` | Metadata is wrong (title, overview, etc) | | `adult` | Marked as adult when it shouldn't be (or vice versa) | | `runtime` | Runtime is incorrect | | `language` | Not in English | | `spam` | Spam or fake season | | `tmdb` | Should use TMDB as the datasource | | `other` | Anything else (add details in `message`) | - [Report a show](https://docs.trakt.tv/reference/postshowsreport.md): #### 🔒 OAuth Required Report a show for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per show. | reason | description | |---|---| | `duplicate` | Duplicate of another show on Trakt | | `remove` | Should be removed from Trakt | | `data_refresh` | Request a full metadata refresh | | `metadata` | Metadata is wrong (title, overview, etc) | | `adult` | Marked as adult when it shouldn't be (or vice versa) | | `runtime` | Runtime is incorrect | | `language` | Not in English | | `spam` | Spam or fake title | | `tmdb` | Should use TMDB as the datasource | | `other` | Anything else (add details in `message`) | - [Report an episode](https://docs.trakt.tv/reference/postshowsepisodereport.md): #### 🔒 OAuth Required Report an episode for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per episode. | reason | description | |---|---| | `duplicate` | Duplicate of another episode on Trakt | | `remove` | Should be removed from Trakt | | `data_refresh` | Request a full metadata refresh | | `metadata` | Metadata is wrong (title, overview, etc) | | `adult` | Marked as adult when it shouldn't be (or vice versa) | | `runtime` | Runtime is incorrect | | `language` | Not in English | | `spam` | Spam or fake episode | | `tmdb` | Should use TMDB as the datasource | | `other` | Anything else (add details in `message`) | - [Refresh show JustWatch links](https://docs.trakt.tv/reference/postshowsjustwatchrefresh.md): #### 🔥 VIP Only 🔒 OAuth Required Queue a refresh of a show's JustWatch watch now links. - [Refresh show metadata](https://docs.trakt.tv/reference/postshowsrefresh.md): #### 🔥 VIP Only 🔒 OAuth Required Queue a full metadata refresh for a show. Pass `images=true` to also refresh the show's images. - [Get all show aliases](https://docs.trakt.tv/reference/getshowsaliases.md): Returns all title aliases for a show. Includes localized and alternate titles when available. - [Get all show certifications](https://docs.trakt.tv/reference/getshowscertifications.md): Returns all content certifications for a show, grouped by country. - [Get show collection progress](https://docs.trakt.tv/reference/getshowsprogresscollection.md): #### 🔒 OAuth Required Returns collection progress for a show including details on all aired seasons and episodes. The `next_episode` will be the next episode the user should collect, if there are no upcoming episodes it will be set to `null`. By default, any hidden seasons will be removed from the response and stats. To include these and adjust the completion stats, set the `hidden` flag to `true`. - [Reset show progress](https://docs.trakt.tv/reference/postshowsprogressreset.md): Reset a show progress. This starts re-watching a show and allows watched progress calculations to ignore previous watches. - [Undo reset show progress](https://docs.trakt.tv/reference/deleteshowsprogressundoreset.md): Undo a show progress reset and restore normal watched progress calculations. - [Get next episode](https://docs.trakt.tv/reference/getshowsnextepisode.md): Returns the next scheduled episode for a show. If no episode is found, a `204` response is returned. - [Get last episode](https://docs.trakt.tv/reference/getshowslastepisode.md): Returns the most recently aired episode for a show. If no episode is found, a `204` response is returned. - [Get single seasons for a show](https://docs.trakt.tv/reference/getshowsseasoninfo.md): Returns a single season for a show including the number of episodes in that season. - [Get all season translations](https://docs.trakt.tv/reference/getshowsseasontranslations.md): Returns all translations for a season, including language, country, and translated title and overview values. - [Get all season comments](https://docs.trakt.tv/reference/getshowsseasoncomments.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for a season. By default, comments are sorted by most `likes`. - [Get lists containing this season](https://docs.trakt.tv/reference/getshowsseasonlists.md): #### 📄 Pagination 😁 Emojis Returns all lists that contain this season. By default, `personal` lists are returned sorted by the most `popular`. - [Get all people for a season](https://docs.trakt.tv/reference/getshowsseasonpeople.md): Returns all cast and crew for a season. Each cast member will have a characters array and a standard person object. - [Get season ratings](https://docs.trakt.tv/reference/getshowsseasonratings.md): Returns the Trakt rating (between 0 and 10), vote count, and rating distribution for a season. Use `?extended=all` to include ratings from TMDB, IMDb, Metascore, and Rotten Tomatoes. External ratings, vote counts, and links can be `null` when unavailable. - [Get season stats](https://docs.trakt.tv/reference/getshowsseasonstats.md): Returns lots of season stats. - [Get users watching right now](https://docs.trakt.tv/reference/getshowsseasonwatching.md): #### ✨ Extended Info Returns all users watching this season right now. - [Get lists containing this episode](https://docs.trakt.tv/reference/getshowsepisodelists.md): #### 📄 Pagination 😁 Emojis Returns all lists that contain this episode. By default, `personal` lists are returned sorted by the most `popular`. - [Get all videos](https://docs.trakt.tv/reference/getshowsepisodevideos.md): #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. - [Get the most favorited shows](https://docs.trakt.tv/reference/getshowsfavorited.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most favorited shows in the specified time `period`, defaulting to `weekly`. - [Get the most played shows](https://docs.trakt.tv/reference/getshowsplayed.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most played shows in the specified time `period`, defaulting to `weekly`. - [Get the most collected shows](https://docs.trakt.tv/reference/getshowscollected.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most collected shows in the specified time `period`, defaulting to `weekly`. - [Get recently updated shows](https://docs.trakt.tv/reference/getshowsupdates.md): Returns all shows updated since the specified UTC date. We recommend storing the latest `updated_at` locally and using it for the next request. - [Get recently updated show Trakt IDs](https://docs.trakt.tv/reference/getshowsupdatedids.md): Returns Trakt IDs for shows updated since the specified UTC date. - [Get social movie recommendations](https://docs.trakt.tv/reference/getsocial_recommendationsmoviesrecommend.md): #### ✨ Extended Info Returns movie recommendations based on the authenticated user social graph. Use `limit`, `watch_window`, and ignore flags to tune the recommendation set. - [Get social show recommendations](https://docs.trakt.tv/reference/getsocial_recommendationsshowsrecommend.md): #### ✨ Extended Info Returns show recommendations based on the authenticated user social graph. Use `limit`, `watch_window`, and ignore flags to tune the recommendation set. - [Get trending media](https://docs.trakt.tv/reference/getmediatrending.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns trending movies and shows. Results are ordered by current watcher activity and can be filtered by media fields or ignored user state. - [Get anticipated media](https://docs.trakt.tv/reference/getmediaanticipated.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns anticipated movies and shows based on list activity. Results can be filtered by media fields or ignored user state. - [Get popular media](https://docs.trakt.tv/reference/getmediapopular.md): #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns popular movies and shows. Results can be filtered by media fields or ignored user state. - [Add notes](https://docs.trakt.tv/reference/postnotescreate.md): #### 🔒 OAuth Required 😁 Emojis Add a new note to a movie, show, season, episode, person, or list. - [Get a note](https://docs.trakt.tv/reference/getnotessummary.md): Returns a single note. - [Update a note](https://docs.trakt.tv/reference/putnotesupdate.md): Update a single note. - [Delete a note](https://docs.trakt.tv/reference/deletenotesdelete.md): Delete a single note. - [Get the attached item](https://docs.trakt.tv/reference/getnotesitem.md): Returns the media item this note is attached to. The media type can be `movie`, `show`, `season`, `episode`, `person`, or `list` and it also returns the standard media object for that media type. - [Get text query results](https://docs.trakt.tv/reference/getsearchquery.md): #### 📄 Pagination ✨ Extended Info Search all text fields that a media object contains (i.e. title, overview, etc). Results are ordered by the most relevant score. Specify the `type` of results by sending a single value or a comma delimited string for multiple types. #### Special Characters Our search engine gives the following characters special meaning when they appear in a query: `+ - && || ! ( ) { } [ ] ^ " ~ * ? : /` To interpret any of these characters literally (and not as a special character), precede the character with a backslash `\` character. #### Search Fields By default, certain text fields are used to search for the `query`. You can optionally specify the `fields` parameter with a single value or comma delimited string for multiple fields. Each `type` has specific `fields` that can be specified. This can be useful if you want to support more strict searches (i.e. title only). | Type | Field | Default | |---|---|---| | `movie` | `title` | ✓ | | | `original_title` | ✓ | | | `translations` | ✓ | | | `aliases` | ✓ | | | `tagline` | | | | `overview` | | | | `people` | | | `show` | `title` | ✓ | | | `original_title` | ✓ | | | `translations` | ✓ | | | `aliases` | ✓ | | | `overview` | | | | `people` | | | `episode` | `title` | ✓ | | | `show_title` | ✓ | | | `overview` | | | `person` | `name` | ✓ | | | `biography` | | | `list` | `name` | ✓ | | | `description` | ✓ | - [Get trending search results](https://docs.trakt.tv/reference/getsearchtrending.md): #### 📄 Pagination ✨ Extended Info Returns globally trending recent searches by `type`. Use `query` to narrow the search text and pagination to move through the result set. - [Add recent search](https://docs.trakt.tv/reference/postsearchrecentadd.md): #### 🔒 OAuth Required Add a recent search to the global search trends. This is not a user-specific recent search history. Send the search request body; a successful create returns `201` with no response body. - [Remove recent search](https://docs.trakt.tv/reference/postsearchrecentremove.md): #### 🔒 OAuth Required Remove a recent search from the global search trends. This is not a user-specific recent search history. Send the search request body; a successful delete returns `204` with no response body. - [Get exact text query results](https://docs.trakt.tv/reference/getsearchexact.md): #### 📄 Pagination ✨ Extended Info Search for exact movie or show matches using the requested search `type` and `query`. Results are paginated and can include extended media details. - [Get ID lookup results](https://docs.trakt.tv/reference/getsearchlookup.md): #### 📄 Pagination ✨ Extended Info Lookup items by external ID. Use `id_type` and `id` to identify the external ID, and optionally send `type` to limit the result media type. - [Get a single person](https://docs.trakt.tv/reference/getpeoplesummary.md): #### ✨ Extended Info Returns a single person's details. #### Gender If available, the `gender` property will be set to `male`, `female`, or `non_binary`. #### Known For Department If available, the `known_for_department` property will be set to `production`, `art`, `crew`, `costume & make-up`, `directing`, `writing`, `sound`, `camera`, `visual effects`, `lighting`, or `editing`. Many people have credits across departments, `known_for` allows you to select their default credits more accurately. - [Get movie credits](https://docs.trakt.tv/reference/getpeoplemovies.md): #### ✨ Extended Info Returns all movies where this person is in the `cast` or `crew`. Each `cast` object will have a `characters` array and a standard `movie` object. The `crew` object will be broken up by department into `production`, `art`, `crew`, `costume & make-up`, `directing`, `writing`, `sound`, `camera`, `visual effects`, `lighting`, and `editing` (if there are people for those crew positions). Each of those members will have a `jobs` array and a standard `movie` object. - [Get show credits](https://docs.trakt.tv/reference/getpeopleshows.md): #### ✨ Extended Info Returns all shows where this person is in the `cast` or `crew`, including the `episode_count` for which they appear. Each `cast` object will have a `characters` array and a standard `show` object. If `series_regular` is `true`, this person is a series regular and not simply a guest star. The `crew` object will be broken up by department into `production`, `art`, `crew`, `costume & make-up`, `directing`, `writing`, `sound`, `camera`, `visual effects`, `lighting`, `editing`, and `created by` (if there are people for those crew positions). Each of those members will have a `jobs` array and a standard `show` object. - [Report a person](https://docs.trakt.tv/reference/postpeoplereport.md): #### 🔒 OAuth Required Report a person for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per person. | reason | description | |---|---| | `duplicate` | Duplicate of another person on Trakt | | `remove` | Should be removed from Trakt | | `data_refresh` | Request a full metadata refresh | | `metadata` | Metadata is wrong (name, biography, etc) | | `adult` | Marked as adult when it shouldn't be (or vice versa) | | `language` | Not in English | | `spam` | Spam or fake person | | `tmdb` | Should use TMDB as the datasource | | `other` | Anything else (add details in `message`) | - [Refresh person metadata](https://docs.trakt.tv/reference/postpeoplerefresh.md): #### 🔥 VIP Only 🔒 OAuth Required Queue a full metadata refresh for a person. Pass `images=true` to also refresh the person's images. - [Get recently updated people](https://docs.trakt.tv/reference/getpeopleupdates.md): Returns all people updated since the specified UTC date. We recommend storing the latest `updated_at` locally and using it for the next request. - [Get recently updated people Trakt IDs](https://docs.trakt.tv/reference/getpeopleupdatedids.md): Returns Trakt IDs for people updated since the specified UTC date. - [Get lists containing this person](https://docs.trakt.tv/reference/getpeoplelists.md): #### 📄 Pagination 😁 Emojis Returns all lists that contain this person. By default, `personal` lists are returned sorted by the most `popular`. - [Get watch now sources](https://docs.trakt.tv/reference/getwatchnowsourcesall.md): #### 🫣 Limited Access This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns all watch now sources supported by Trakt, including provider metadata used by watch now routes. - [Get watch now sources by country](https://docs.trakt.tv/reference/getwatchnowsourcescountry.md): #### 🫣 Limited Access This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns watch now sources available in a country. Use the `countryCode` path parameter to request country-specific provider metadata. - [Report a season](https://docs.trakt.tv/reference/postseasonsreport.md): #### 🔒 OAuth Required Report a season for moderator review. Send a reason and optional message in the request body; duplicate pending reports return `409`. - [Get episode watch now sources](https://docs.trakt.tv/reference/getepisodeswatchnow.md): #### 🫣 Limited Access ✨ Extended Info This endpoint is documented for visibility, but access is currently limited and may not be available to all API consumers. Returns streaming and watch now sources for an episode in the requested country. Use `links` to include provider links when available. - [Report an episode](https://docs.trakt.tv/reference/postepisodesreport.md): #### 🔒 OAuth Required Report an episode for moderator review. Send a reason and optional message in the request body; duplicate pending reports return `409`. - [Get smart list](https://docs.trakt.tv/reference/getsmart_listssummary.md): #### 🔓 OAuth Optional 😁 Emojis Returns a single smart list definition by its globally-unique slug. Use the [**/smart-lists/:list_id/items**](#reference/smart-lists) method to get the dynamic items this smart list resolves to. > ### Note > _Only public smart lists return data unless you send OAuth as the owner._ - [Get smart list items](https://docs.trakt.tv/reference/getsmart_listsitems.md): #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info 🎚 Filters 😁 Emojis Returns the dynamic items a smart list resolves to. Use `type`, `sort_by`, and `sort_how` to control the returned item set and order, plus query filters and pagination to refine the result set. - [About Comments](https://docs.trakt.tv/reference/about-comments.md) - [Get all users who liked a comment](https://docs.trakt.tv/reference/getcommentslikes.md): #### 📄 Pagination Returns all users who liked a comment. If you only need the `replies` count, the main `comment` object already has that, so no need to use this method. - [Like a comment](https://docs.trakt.tv/reference/postcommentslike.md): #### 🔒 OAuth Required Votes help determine popular comments. Only one like is allowed per comment per user. - [Remove like on a comment](https://docs.trakt.tv/reference/deletecommentsunlike.md): #### 🔒 OAuth Required Remove a like on a comment. - [Get replies for a comment](https://docs.trakt.tv/reference/getcommentsreplies.md): #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all replies for a comment. It is possible these replies could have replies themselves, so in that case you would just call [**/comments/:id/replies**](/reference/comments/replies/) again with the new comment `id`. > ### Note > _If you send OAuth, replies from blocked users will be automatically filtered out._ - [Post a reply for a comment](https://docs.trakt.tv/reference/postcommentsreply.md): #### 🔒 OAuth Required 😁 Emojis Add a new reply to an existing comment. Make sure to allow and encourage *spoilers* to be indicated in your app and follow the rules listed above. > ### Note > Replies can only be added to top level comments. If you try to reply to a reply, a `404` HTTP status code is returned. #### JSON POST Data | Key | Type | Default | Value | |---|---|---|---| | `comment` * | string | | Text for the reply. | | `spoiler` | boolean | `false` | Is this a spoiler? | - [Update a comment or reply](https://docs.trakt.tv/reference/putcommentsedit.md): #### 🔒 OAuth Required 😁 Emojis Update a single comment. The OAuth user must match the author of the comment in order to update it. If not, a `401` HTTP status is returned. #### JSON POST Data | Key | Type | Default | Value | |---|---|---|---| | `comment` | string | | Text for the comment. | | `spoiler` | boolean | `false` | Is this a spoiler? | - [Delete a comment or reply](https://docs.trakt.tv/reference/deletecommentsdelete.md): #### 🔒 OAuth Required Delete a single comment. The OAuth user must match the author of the comment in order to delete it. If not, a `401` HTTP status code is returned. The comment must also be less than 2 weeks old or have 0 replies. If not, a `409` HTTP status is returned. - [Post a comment](https://docs.trakt.tv/reference/postcommentspost.md): #### 🔒 OAuth Required 😁 Emojis Add a new comment to a movie, show, season, episode, or list. Make sure to allow and encourage *spoilers* to be indicated in your app and follow the rules listed above. #### JSON POST Data | Key | Type | Default | Value | |---|---|---|---| | item * | object | | `movie`, `show`, `season`, `episode`, or `list` object. (see examples ->) | | `comment` * | string | | Text for the comment. | | `spoiler` | boolean | `false` | Is this a spoiler? | | `sharing` | object | | Control sharing to any connected social networks. (see below ↓) | #### Sharing The `sharing` object is optional and will apply the user's settings if not sent. If `sharing` is sent, each key will override the user's setting for that social network. Send `true` to post or `false` to not post on the indicated social network. You can see which social networks a user has connected with the [**/users/settings**](/reference/users/settings) method. | Key | Type | |---|---| | `twitter` | boolean | | `tumblr` | boolean | | `medium` | boolean | - [Get reaction summary](https://docs.trakt.tv/reference/getcommentsreactionssummary.md): Returns reaction totals for a comment, grouped by reaction type. - [Get comment reactions](https://docs.trakt.tv/reference/getcommentsreactionsall.md): #### 📄 Pagination ✨ Extended Info Returns users and reaction details for every reaction on a comment. Use pagination and `extended` to control the response. - [Add comment reaction](https://docs.trakt.tv/reference/postcommentsreactionsadd.md): #### 🔒 OAuth Required Add a reaction to a comment. Use `reaction_type` to choose the reaction; a successful create returns `201` with no response body. - [Remove comment reaction](https://docs.trakt.tv/reference/deletecommentsreactionsremove.md): #### 🔒 OAuth Required Remove a reaction from a comment. Use `reaction_type` to choose the reaction; a successful delete returns `204` with no response body. - [Report a comment](https://docs.trakt.tv/reference/postcommentsreport.md): #### 🔒 OAuth Required Report a comment for moderator review. Send a `reason` and optional `message` with additional context. A user can only have one `pending` report per comment. | reason | description | |---|---| | `spoilers` | Contains spoilers | | `language` | Not in English | | `abusive` | Harassment or abusive behavior | | `spam` | Spam or self-promotion | | `bigotry` | Bigotry, hate speech, or discrimination | | `political` | Political attack | | `offtopic` | Off topic | | `support` | Support question | | `duplicate` | Duplicate comment | | `too_short` | Too short to be useful | | `other` | Anything else (add details in `message`) | - [Get a comment or reply](https://docs.trakt.tv/reference/getcommentssummary.md): #### 😁 Emojis Returns a single comment and indicates how many replies it has. Use [**/comments/:id/replies**](/reference/comments/replies/) to get the actual replies. - [Get the attached media item](https://docs.trakt.tv/reference/getcommentsitem.md): #### ✨ Extended Info Returns the media item this comment is attached to. The media type can be `movie`, `show`, `season`, `episode`, or `list` and it also returns the standard media object for that media type. - [Get trending comments](https://docs.trakt.tv/reference/getcommentstrending.md): #### 📄 Pagination ✨ Extended Info 😁 Emojis Returns all comments with the most likes and replies over the last 7 days. You can optionally filter by the `comment_type` and media `type` to limit what gets returned. If you want to `include_replies` that will return replies in place alongside top level comments. - [Get recently created comments](https://docs.trakt.tv/reference/getcommentsrecent.md): #### 📄 Pagination ✨ Extended Info 😁 Emojis Returns the most recently written comments across all of Trakt. You can optionally filter by the `comment_type` and media `type` to limit what gets returned. If you want to `include_replies` that will return replies in place alongside top level comments. - [Get recently updated comments](https://docs.trakt.tv/reference/getcommentsupdates.md): #### 📄 Pagination ✨ Extended Info 😁 Emojis Returns the most recently updated comments across all of Trakt. You can optionally filter by the `comment_type` and media `type` to limit what gets returned. If you want to `include_replies` that will return replies in place alongside top level comments. - [Get show certifications](https://docs.trakt.tv/reference/getcertificationsshows.md): Returns show certifications grouped by country, including certification name, slug, and description. - [Get movie certifications](https://docs.trakt.tv/reference/getcertificationsmovies.md): Returns movie certifications grouped by country, including certification name, slug, and description. - [Get certifications](https://docs.trakt.tv/reference/getcertificationslist.md): Get a list of all certifications, including names, slugs, and descriptions. - [Get countries](https://docs.trakt.tv/reference/getcountrieslist.md): Get a list of all countries, including names and codes. - [Get genres](https://docs.trakt.tv/reference/getgenreslist.md): Get a list of all genres, including names and slugs. #### Subgenres Send `?extended=subgenres` to get a list of subgenres for each genre. You can get more creative with advanced filters by using the subgenres in your app. - [Get languages](https://docs.trakt.tv/reference/getlanguageslist.md): Get a list of all languages, including names and codes. - [Get networks](https://docs.trakt.tv/reference/getnetworkslist.md): Get a list of all TV networks, including names. - [About Scrobble](https://docs.trakt.tv/reference/about-scrobble.md) - [Start watching in a media center](https://docs.trakt.tv/reference/postscrobblestart.md): #### 🔒 OAuth Required Use this method when the video initially starts playing or is unpaused. This will remove any playback progress if it exists. > ### Note > _A watching status will auto expire after the remaining runtime has elapsed. There is no need to call this method again while continuing to watch the same item._ #### JSON POST Data | Key | Type | Value | |---|---|---| | item * | object | `movie` or `episode` object. (see examples ->) | | `progress` * | float | Progress percentage between 0 and 100. | - [Pause watching in a media center](https://docs.trakt.tv/reference/postscrobblepause.md): #### 🔒 OAuth Required Pause an active scrobble for a movie or episode. Send the media object and current progress in the request body; the response returns the updated scrobble state. - [Stop or finish watching in a media center](https://docs.trakt.tv/reference/postscrobblestop.md): #### 🔒 OAuth Required Use this method when the video is stopped or finishes playing on its own. If the progress is above 80%, the video will be scrobbled and the `action` will be set to **scrobble**. A unique history `id` (64-bit integer) will be returned and can be used to reference this `scrobble` directly. If the progress is between 1% and 79%, it will be treated as a *pause* and the `action` will be set to **pause**. The playback progress will be saved and [**/sync/playback**](/reference/sync/playback/) can be used to resume the video from this exact position. > ### Note > _If the progress is less than 1%, you'll get a `422` HTTP status code response and the scrobble will be ignored._ #### JSON POST Data | Key | Type | Value | |---|---|---| | item * | object | `movie` or `episode` object. (see examples ->) | | `progress` * | flloat | Progress percentage between 0 and 100. | > ### Note > _If the same item was just scrobbled, a `409` HTTP status code will returned to avoid scrobbling a duplicate. The response will contain a `watched_at` timestamp when the item was last scrobbled and a `expires_at` timestamp when the item can be scrobbled again._ - [Get team members](https://docs.trakt.tv/reference/getteammembers.md): #### ✨ Extended Info Returns Trakt team members. Use `extended` to include additional person details and images when available. - [Get streaming connections](https://docs.trakt.tv/reference/getyounifyconnections.md): #### 🔒 OAuth Required Lists every connectable streaming service with the current user's connection status merged in, so a settings grid can render each tile in one pass. Read-only — never creates a remote younify user. > ### IMPORTANT > _**Array order is significant.** Clients must preserve the response order when rendering the grid; the list is returned in the intended display order._ `vip: false` is the free tier. `connectable` reflects whether the current user may connect the service on their plan. `connected` plus `active` indicate a healthy link (`active: false` is a broken link). `profile` and `last_synced_at` are null when not connected, and `last_synced_at` is normalized to `.000Z`. - [Create a streaming connection](https://docs.trakt.tv/reference/postyounifyconnect.md): #### 🔒 OAuth Required Mints a signed younify web-auth URL for the client to open. Accepts the client's own `return_url` (deep link / universal link), validated against trakt-owned destinations only (`trakt://…` or `https://*.trakt.tv`). A `422` is returned when the service is not connectable on the user's plan, and a `400` when the `return_url` is missing/invalid or no URL could be minted. - [Refresh a streaming service](https://docs.trakt.tv/reference/postyounifyrefresh.md): #### 🔒 OAuth Required Queue / force a re-sync of a connected streaming service for the authenticated user. - [Refresh a streaming service (full re-sync)](https://docs.trakt.tv/reference/postyounifyrefreshall.md): #### 🔒 OAuth Required Queue / force a re-sync of a connected streaming service for the authenticated user. The trailing `all_data` segment forces a full re-sync of all data rather than an incremental one. - [Unlink a streaming service](https://docs.trakt.tv/reference/deleteyounifydisconnect.md): #### 🔒 OAuth Required Unlink a streaming service from the authenticated user.