FORMAT: 1A HOST: https://api.trakt.tv # Trakt API At Trakt, we collect lots of interesting information about what tv shows and movies everyone is watching. Part of the fun with such data is making it available for anyone to mash up and use on their own site or app. The Trakt API was made just for this purpose. It is very easy to use, you basically call a URL and get some JSON back. More complex API calls (such as adding a movie or show to your collection) involve sending us data. These are still easy to use, you simply POST some JSON data to a specific URL. Make sure to check out the [**Required Headers**](#introduction/required-headers) and [**Authentication**](#reference/authentication-oauth) sections for more info on what needs to be sent with each API call. Also check out the [**Terminology**](#introduction/terminology) section insight into the features Trakt supports. # Create an App To use the Trakt API, you'll need to [**create a new API app**](https://trakt.tv/oauth/applications/new). # Stay Connected API discussion and bugs should be posted in the [**GitHub Developer Forum**](https://github.com/trakt/trakt-api/issues) and *watch* the repository if you'd like to get notifications. # API URL The API should always be accessed over SSL. ``` https://api.trakt.tv ``` If you would like to use our sandbox environment to not fill production with test data, use this URL over SSL. ``` https://api-staging.trakt.tv ``` > ### 🅽🅾🆃🅴 > _Staging is a completely separate environment, so you'll need to [**create a new API app on staging**](https://staging.trakt.tv/oauth/applications/new)._ # Verbs The API uses restful verbs. | Verb | Description | |---|---| | `GET` | Select one or more items. Success returns `200` status code. | | `POST` | Create a new item. Success returns `201` status code. | | `PUT` | Update an item. Success returns `200` status code. | | `DELETE` | Delete an item. Success returns `200` or `204` status code. | # Status Codes The API will respond with one of the following HTTP status codes. | Code | Description | |---|---| | `200` | Success | `201` | Success - *new resource created (POST)* | `204` | Success - *no content to return (DELETE)* | `400` | Bad Request - *request couldn't be parsed* | `401` | Unauthorized - *OAuth must be provided* | `403` | Forbidden - *invalid API key or unapproved app* | `404` | Not Found - *method exists, but no record found* | `405` | Method Not Found - *method doesn't exist* | `409` | Conflict - *resource already created* | `410` | Deactivated User Account - *user must log in on the website to reactivate* | `412` | Precondition Failed - *use application/json content type* | `420` | Account Limit Exceeded - *list count, item count, etc* | `422` | Unprocessable Entity - *validation errors* | `423` | Locked User Account - *redirect to history analysis in settings* | `426` | VIP Only - *user must upgrade to VIP* | `429` | Rate Limit Exceeded | `500` | Server Error - *please open a support ticket* | `502` | Service Unavailable - *server overloaded (try again in 30s)* | `503` | Service Unavailable - *server overloaded (try again in 30s)* | `504` | Service Unavailable - *server overloaded (try again in 30s)* | `520` | Service Unavailable - *Cloudflare error* | `521` | Service Unavailable - *Cloudflare error* | `522` | Service Unavailable - *Cloudflare error* # Required Headers You'll need to send some headers when making API calls to identify your application, set the version and set the content type to JSON. | Header | Value | |---|---| | `Content-Type` * | `application/json` | | `User-Agent` * | We suggest using your app and version like `MyAppName/1.0.0` | | `trakt-api-key` * | Your `client_id` listed under your Trakt applications. | | `trakt-api-version` * | `2` | API version to use. All `POST`, `PUT`, and `DELETE` methods require a valid OAuth `access_token`. Some `GET` calls require OAuth and others will return user specific data if OAuth is sent. Methods that 🔒 **require** or have 🔓 **optional** OAuth will be indicated. Your OAuth library should take care of sending the auth headers for you, but for reference here's how the Bearer token should be sent. | Header | Value | |---|---| | `Authorization` | `Bearer [access_token]` | # Rate Limiting All API methods are rate limited. A `429` HTTP status code is returned when the limit has been exceeded. Check the headers for detailed info, then try your API call in `Retry-After` seconds. | Header | Value | |---|---| | `X-Ratelimit` | `{"name":"UNAUTHED_API_GET_LIMIT","period":300,"limit":1000,"remaining":0,"until":"2020-10-10T00:24:00Z"}` | | `Retry-After` | `10` | Here are the current limits. There are separate limits for authed (user level) and unauthed (application level) calls. We'll continue to adjust these limits to optimize API performance for everyone. The goal is to prevent API abuse and poor coding, but allow users to use apps normally. | Name | Verb | Methods | Limit | |---|---|---|---| | `AUTHED_API_POST_LIMIT` | `POST`, `PUT`, `DELETE` | all | 1 call per second | | `AUTHED_API_GET_LIMIT` | `GET` | all | 1000 calls every 5 minutes | | `UNAUTHED_API_GET_LIMIT` | `GET` | all | 1000 calls every 5 minutes | # Locked User Account A `423` HTTP status code is returned when the OAuth user has a locked user account. Please redirect the user to their [**history analysis in settings**](https://trakt.tv/settings/data) to run a history analysis and unlock their account. | Header | Value | |---|---| | `X-Account-Locked` | `true` or `false` | # Deactivated User Account A `410` HTTP status code is returned when the OAuth user has a deactivated user account. Please instruct the user to log in on the [**Trakt website**](https://trakt.tv) to reactivate their account. | Header | Value | |---|---| | `X-Account-Deactivated` | `true` or `false` | # VIP Methods Some API methods are tagged 🔥 **VIP Only**. A `426` HTTP status code is returned when the user isn't a VIP, indicating they need to sign up for [**Trakt VIP**](https://trakt.tv/vip) in order to use this method. In your app, please open a browser to `X-Upgrade-URL` so the user can sign up for Trakt VIP. | Header | Value | |---|---| | `X-Upgrade-URL` | `https://trakt.tv/vip` | Some API methods are tagged 🔥 **VIP Enhanced**. A `420` HTTP status code is returned when the user has exceeded their account limit. Signing up for [**Trakt VIP**](https://trakt.tv/vip) will increase these limits. If the user isn't a VIP, please open a browser to `X-Upgrade-URL` so the user can sign up for Trakt VIP. If they are already VIP and still exceeded the limit, please display a message indicating this. | Header | Value | |---|---| | `X-Upgrade-URL` | `https://trakt.tv/vip` | | `X-VIP-User` | `true` or `false` | | `X-Account-Limit` | Limit allowed. | # Pagination Some methods are paginated. Methods with 📄 **Pagination** will load 1 page of 10 items by default. Methods with 📄 **Pagination Optional** will load all items by default. In either case, append a query string like `?page={page}&limit={limit}` to the URL to influence the results. | Parameter | Type | Default | Value | |---|---|---|---| | `page` | integer | `1` | Number of page of results to be returned. | | `limit` | integer | `10` | Number of results to return per page. | All paginated methods will return these HTTP headers. | Header | Value | |---|---| | `X-Pagination-Page` | Current page. | | `X-Pagination-Limit` | Items per page. | | `X-Pagination-Page-Count` | Total number of pages. | | `X-Pagination-Item-Count` | Total number of items. | # Extended Info By default, all methods will return minimal info for movies, shows, episodes, people, and users. Minimal info is typically all you need to match locally cached items and includes the `title`, `year`, and `ids`. However, you can request different extended levels of information by adding `?extended={level}` to the URL. Send a comma separated string to get multiple types of extended info. > ### 🅽🅾🆃🅴 > _This returns a lot of extra data, so please only use extended parameters if you actually need them!_ | Level | Description | |---|---| | `images` | Minimal info and all images. | | `full` | Complete info for an item. | | `full,images` | Complete info and all images. | | `metadata` | **Collection only.** Additional video and audio info. | # Filters Some `movies`, `shows`, and `calendars` methods support additional filters and will be tagged with 🎚 **Filters**. Applying these filters refines the results and helps your users to more easily discover new items. Add a query string (i.e. `?years=2016&genres=action`) with any filters you want to use. Some filters allow multiples which can be sent as comma delimited parameters. For example, `?genres=action,adventure` would match the `action` OR `adventure` genre. *Please note*, subgenres are currently a technical preview. We're currently in the process of smoothing this out. > ### 🅽🅾🆃🅴 > _Make sure to properly URL encode the parameters including spaces and special characters._ #### Common Filters | Parameter | Multiples | Example | Value | |---|---|---|---| | `query` | | `batman` | Search titles and descriptions. | | `years` | | `2016` | 4 digit year or range of years. | | `genres` | ✓ | `action` | [Genre slugs.](#reference/genres) | | `subgenres` | ✓ | `android` | [Subgenre slugs.](#reference/subgenres) | | `languages` | ✓ | `en` | [2 character language code.](#reference/languages) | | `countries` | ✓ | `us` | [2 character country code.](#reference/countries) | | `runtimes` | | `30-90` | Range in minutes. | | `studio_ids` | ✓ | `42` | Trakt studio ID. | #### Rating Filters Trakt, TMDB, and IMDB ratings apply to `movies`, `shows`, and `episodes`. Rotten Tomatoes and Metacritic apply to `movies`. | Parameter | Multiples | Example | Value | |---|---|---|---| | `ratings` | | `75-100` | Trakt rating range between `0` and `100`. | | `votes` | | `5000-10000` | Trakt vote count between `0` and `100000`. | | `tmdb_ratings` | | `5.5-10.0` | TMDB rating range between `0.0` and `10.0`. | | `tmdb_votes` | | `5000-10000` | TMDB vote count between `0` and `100000`. | | `imdb_ratings` | | `5.5-10.0` | IMDB rating range between `0.0` and `10.0`. | | `imdb_votes` | | `5000-10000` | IMDB vote count between `0` and `3000000`. | | `rt_meters` | | `55-1000` | Rotten Tomatoes tomatometer range between `0` and `100`. | | `rt_user_meters` | | `65-100` | Rotten Tomatoes audience score range between `0` and `100`. | | `metascores` | | `5.5-10.0` | Metacritic score range between `0` and `100`. | #### Movie Filters | Parameter | Multiples | Example | Value | |---|---|---|---| | `certifications` | ✓ | `pg-13` | US content certification. | #### Show Filters | Parameter | Multiples | Example | Value | |---|---|---|---| | `certifications` | ✓ | `tv-pg` | US content certification. | | `network_ids` | ✓ | `53` | Trakt network ID. | | `status` | ✓ | `ended` | Set to `returning series`, `continuing`, `in production`, `planned`, `upcoming`, `pilot`, `canceled`, or `ended`. | #### Episode Filters | Parameter | Multiples | Example | Value | |---|---|---|---| | `certifications` | ✓ | `tv-pg` | US content certification. | | `network_ids` | ✓ | `53` | Trakt network ID. | | `episode_types` | ✓ | `mid_season_premiere` | Set to `standard`, `series_premiere`, `season_premiere`, `mid_season_finale`, `mid_season_premiere`, `season_finale`, or `series_finale`. | # CORS When creating your API app, specify the JavaScript (CORS) origins you'll be using. We use these origins to return the headers needed for CORS. # Dates All dates will be GMT and returned in the ISO 8601 format like `2014-09-01T09:10:11.000Z`. Adjust accordingly in your app for the user's local timezone. # Emojis We use short codes for emojis like `:smiley:` and `:raised_hands:` and render them on the Trakt website using [**JoyPixels**](https://www.joypixels.com/) _(verion 6.6.0)_. Methods that support emojis are tagged with 😁 **Emojis**. For POST methods, you can send standard unicode emojis and we'll automatically convert them to short codes. For GET methods, we'll return the unicode emojis if possible, but some short codes might also be returned. It's up to your app to convert short codes back to unicode emojis. # Standard Media Objects All methods will accept or return standard media objects for `movie`, `show`, `season`, `episode`, `person`, and `user` items. Here are examples for all minimal objects. #### movie ``` { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } } ``` #### show ``` { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } ``` #### season ``` { "number": 0, "ids": { "trakt": 1, "tvdb": 439371, "tmdb": 3577 } } ``` #### episode ``` { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 16, "tvdb": 349232, "imdb": "tt0959621", "tmdb": 62085 } } ``` #### person ``` { "name": "Bryan Cranston", "ids": { "trakt": 142, "slug": "bryan-cranston", "imdb": "nm0186505", "tmdb": 17419 } } ``` #### user ``` { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": true, "ids": { "slug": "sean" } } ``` # Images #### Trakt Images Trakt can return images by appending `?extended=images` to most URLs. This will return all images for a `movie`, `show`, `season`, `episode`, or `person`. Images are returned in a `images` object with keys for each image type. Each image type is an array of image URLs, but only 1 image URL will be returned for now. This is just future proofing. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > **Please cache all images!** All images are required to be cached in your app or server and not loaded directly from our CDN. Hotlinking images is not allowed and will be blocked. > ### 🅽🅾🆃🅴 > All images are returned in WebP format for reduced file size, at the same image quality. You'll also need to prepend the https:// prefix to all image URLs. ### Example Images Object ```json { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 12601, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 }, "images": { "fanart": [ "walter-r2.trakt.tv/images/movies/000/012/601/fanarts/medium/5aab754f58.jpg.webp" ], "poster": [ "walter-r2.trakt.tv/images/movies/000/012/601/posters/thumb/e0d9dd35c5.jpg.webp" ], "logo": [ "walter-r2.trakt.tv/images/movies/000/012/601/logos/medium/dbce70b4aa.png.webp" ], "clearart": [ "walter-r2.trakt.tv/images/movies/000/012/601/cleararts/medium/513a3688d1.png.webp" ], "banner": [ "walter-r2.trakt.tv/images/movies/000/012/601/banners/medium/71dc0c3258.jpg.webp" ], "thumb": [ "walter-r2.trakt.tv/images/movies/000/012/601/thumbs/medium/fcd7d7968c.jpg.webp" ] } } ``` #### External Images If you want more variety of images, there are several external services you can use. The standard Trakt media objects for all `movie`, `show`, `season`, `episode`, and `person` items include an `ids` object. These `ids` map to other services like [TMDB](https://www.themoviedb.org), [TVDB](https://thetvdb.com), [Fanart.tv](https://fanart.tv), [IMDB](https://www.imdb.com), and [OMDB](https://www.omdbapi.com/). Most of these services have free APIs you can use to grab lots of great looking images. Here’s a chart to help you find the best artwork for your app. [**We also wrote an article to help with this.**](https://medium.com/api-news/how-to-find-the-best-images-516045bcc3b6) | Media | Type | [TMDB](https://developers.themoviedb.org/3) | [TVDB](https://api.thetvdb.com/swagger) | [Fanart.tv](http://docs.fanarttv.apiary.io) | [OMDB](https://www.omdbapi.com) | |---|---|---|---|---|---| | `shows` | `poster` | ✓ | ✓ | ✓ | ✓ | | | `fanart` | ✓ | ✓ | ✓ | | | | `banner` | | ✓ | ✓ | | | | `logo` | ✓ | | ✓ | | | | `clearart` | | | ✓ | | | | `thumb` | | | ✓ | | | `seasons` | `poster` | ✓ | ✓ | ✓ | | | | `banner` | | ✓ | ✓ | | | | `thumb` | | | ✓ | | | `episodes` | `screenshot` | ✓ | ✓ | | | | `movies` | `poster` | ✓ | | ✓ | ✓ | | | `fanart` | ✓ | | ✓ | | | | `banner` | | | ✓ | | | | `logo` | ✓ | | ✓ | | | | `clearart` | | | ✓ | | | | `thumb` | | | ✓ | | | `person` | `headshot` | ✓ | | | | | | `character` | | ✓ | | | # Website Media Links There are several ways to construct direct links to media on the Trakt website. The website itself uses slugs so the URLs are more readable. | Type | URL | |---|---| | `movie` | `/movies/:id` | | | `/movies/:slug` | | `show` | `/shows/:id` | | | `/shows/:slug` | | `season` | `/shows/:id/seasons/:num` | | | `/shows/:slug/seasons/:num` | | `episode` | `/shows/:id/seasons/:num/episodes/:num` | | | `/shows/:slug/seasons/:num/episodes/:num` | | `person` | `/people/:id` | | | `/people/:slug` | | `comment` | `/comments/:id` | | `list` | `/lists/:id` | You can also create links using the Trakt, IMDB, TMDB, or TVDB IDs. We recommend using the Trakt ID if possible since that will always have full coverage. If you use the search url without an `id_type` it will return search results if multiple items are found. | Type | URL | |---|---| | `trakt` | `/search/trakt/:id` | | | `/search/trakt/:id?id_type=movie` | | | `/search/trakt/:id?id_type=show` | | | `/search/trakt/:id?id_type=season` | | | `/search/trakt/:id?id_type=episode` | | | `/search/trakt/:id?id_type=person` | | `imdb` | `/search/imdb/:id` | | `tmdb` | `/search/tmdb/:id` | | | `/search/tmdb/:id?id_type=movie` | | | `/search/tmdb/:id?id_type=show` | | | `/search/tmdb/:id?id_type=episode` | | | `/search/tmdb/:id?id_type=person` | | `tvdb` | `/search/tvdb/:id` | | | `/search/tvdb/:id?id_type=show` | | | `/search/tvdb/:id?id_type=episode` | # Third Party Libraries All of the libraries listed below are user contributed. If you find a bug or missing feature, please contact the developer directly. These might help give your project a head start, but we can't provide direct support for any of these libraries. Please help us keep this list up to date. | Language | Name | Repository | |---|---|---| | `C#` | `Trakt.NET` | https://github.com/henrikfroehling/Trakt.NET | | | `TraktSharp` | https://github.com/wwarby/TraktSharp | | `C++` | `libtraqt` | https://github.com/RobertMe/libtraqt | | `Clojure` | `clj-trakt` | https://github.com/niamu/clj-trakt | | `Java` | `trakt-java` | https://github.com/UweTrottmann/trakt-java | | `Kotlin` | `trakt-api` | https://github.com/MoviebaseApp/trakt-api | | `Node.js` | `Trakt.tv` | https://github.com/vankasteelj/trakt.tv | | | `TraktApi2` | https://github.com/PatrickE94/traktapi2 | | `Python` | `trakt.py` | https://github.com/fuzeman/trakt.py | | | `pyTrakt` | https://github.com/moogar0880/PyTrakt | | `R` | `tRakt` | https://github.com/jemus42/tRakt | | `React Native` | `nodeless-trakt` | https://github.com/kdemoya/nodeless-trakt | | `Ruby` | `omniauth-trakt` | https://github.com/wafcio/omniauth-trakt | | | `omniauth-trakt` | https://github.com/alextakitani/omniauth-trakt | | `Swift` | `TraktKit` | https://github.com/MaxHasADHD/TraktKit | | | `AKTrakt` | https://github.com/arsonik/AKTrakt | # Terminology Trakt has a lot of features and here's a chart to help explain the differences between some of them. | Term | Description | |---|---| | `scrobble` | Automatic way to track what a user is watching in a media center. | | `checkin` | Manual action used by mobile apps allowing the user to indicate what they are watching right now. | | `history` | All watched items (scrobbles, checkins, watched) for a user. | | `collection` | Items a user has available to watch including Blu-Rays, DVDs, and digital downloads. | | `watchlist` | Items a user wants to watch in the future. Once watched, they are auto removed from this list. | | `list` | Personal list for any purpose. Items are not auto removed from any personal lists. | | `favorites` | A user's top 50 TV shows and movies. | # Group Authentication - OAuth The API uses OAuth2. If you know what's up with OAuth2, grab your library and starting rolling. If you have access to a web browser (mobile app, desktop app, website), use standard **OAuth**. If you don't have web browser access (media center plugins, smart watches, smart TVs, command line scripts, system services), use **Device** authentication. To obtain a `client_id` and `client_secret`, create an application on the Trakt website. Here are some helpful links to get your started: - [Create a new API app](https://trakt.tv/oauth/applications/new) - [View your API apps](https://trakt.tv/oauth/applications) --- #### Application Flow 1. **Redirect to request Trakt access.** Using the [**/oauth/authorize**](/reference/authentication-oauth/authorize) method, construct then redirect to this URL. The Trakt website will request permissions for your app and the user will have the opportunity to sign up for a new Trakt account or sign in with their existing account. 2. **Trakt redirects back to your site.** If the user accepts your request, Trakt redirects back to your site with a temporary code in a `code` GET parameter as well as the state (if provided) in the previous step in a `state` parameter. If the states don’t match, the request has been created by a third party and the process should be aborted. 3. **Exchange the code for an access token.** If everything looks good in step 2, exchange the `code` for an access token using the [**/oauth/token**](reference/authentication-oauth/get-token/) method. Save the `access_token` so your app can authenticate the user by sending the `Authorization` header as indicated below or in any example code. 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. ## Authorize [/oauth/authorize{?response_type,client_id,redirect_uri,state}] + Parameters + response_type (required, string, `code`) ... Must be set to code. + client_id (required, string, ` `) ... Get this from your app settings. + redirect_uri (required, string, ` `) ... URI specified in your app settings. + state (optional, string, ` `) ... State variable for CSRF purposes. + signup (optional, string, `true`) ... Default to the sign up page. ### Authorize Application [GET] 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. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _Use the website **https://trakt.tv** hostname when creating this URL and not the API URL._ #### 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. | + Request (application/json) ``` https://trakt.tv/oauth/authorize?response_type=code&client_id=9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f&redirect_uri=urn:ietf:wg:oauth:2.0:oob ``` + Body + Response 200 + Body ## Get Token [/oauth/token] ### Exchange code for access_token [POST] Use the authorization `code` GET parameter sent back to your `redirect_uri` to get an `access_token`. Save the `access_token` so your app can authenticate the user by sending the `Authorization` header. 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. #### JSON POST Data | Key | Type | Value | |---|---|---| | `code` * | string | Authorization code. | | `client_id` * | string | Get this from your app settings. | | `client_secret` * | string | Get this from your app settings. | | `redirect_uri` * | string | URI specified in your app settings. | | `grant_type` * | string | `authorization_code` | + Request (application/json) + Body { "code": "fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0", "client_id": "9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret": "d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2", "redirect_uri": "urn:ietf:wg:oauth:2.0:oob", "grant_type": "authorization_code" } + Response 200 (application/json) If the `code` is valid, you'll get the `access_token` back. + Body { "access_token": "dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781", "token_type": "bearer", "expires_in": 86400, "refresh_token": "76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c", "scope": "public", "created_at": 1487889741 } + Response 401 (application/json) If the `code` is invalid, you'll get a `401` error. + Body { "error": "invalid_grant", "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." } ## Refresh Token [/oauth/token] ### Exchange refresh_token for access_token [POST] Use the `refresh_token` to get a new `access_token` without asking the user to re-authenticate. The `access_token` is valid for **7 days** before it needs to be refreshed again. #### JSON POST Data | Key | Type | Value | |---|---|---| | `refresh_token` * | string | Saved from the initial token method. | | `client_id` * | string | Get this from your app settings. | | `client_secret` * | string | Get this from your app settings. | | `redirect_uri` * | string | URI specified in your app settings. | | `grant_type` * | string | `refresh_token` | + Request (application/json) + Body { "refresh_token": "fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0", "client_id": "9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret": "d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2", "redirect_uri": "urn:ietf:wg:oauth:2.0:oob", "grant_type": "refresh_token" } + Response 200 (application/json) If the `refresh_token` is valid, you'll get the `access_token` back. + Body { "access_token": "dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781", "token_type": "bearer", "expires_in": 86400, "refresh_token": "76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c", "scope": "public", "created_at": 1487889741 } + Response 401 (application/json) If the `refresh_token` is invalid, you'll get a `401` error. + Body { "error": "invalid_grant", "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." } ## Revoke Token [/oauth/revoke] ### Revoke an access_token [POST] 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. | + Request (application/json) + Body { "token": "fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0", "client_id": "9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret": "d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2" } + Response 200 (application/json) + Body {} # Group Authentication - Devices Device authentication is for apps and services with limited input or display capabilities. This include media center plugins, smart watches, smart TVs, command line scripts, and system services. Your app displays an alphanumeric code (typically 8 characters) to the user. They are then instructed to visit the verification URL on their computer or mobile device. After entering the code, the user will be prompted to grant permission for your app. After your app gets permissions, the device receives an `access_token` and works like standard OAuth from that point on. More details below. --- #### Application Flow 1. **Generate codes.** Your app calls [**/oauth/device/code**](/reference/authentication-devices/code) to generate new codes. Save this entire response for later use. 2. **Display the code.** Display the `user_code` and instruct the user to visit the `verification_url` on their computer or mobile device. 3. **Poll for authorization.** Poll the [**/oauth/device/token**](/reference/authentication-devices/token) method to see if the user successfully authorizes your app. Use the `device_code` and poll at the `interval` (in seconds) to check if the user has authorized your app. Check the docs below for the specific error codes you need to handle. 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.** 4. **Successful authorization.** 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. It's normal OAuth from this point. --- #### User Flow 1. **Call to action.** Consider your user experience when asking a user to connect their Trakt account. For some devices this will be right away, and for others it might be later in the experience. 2. **Display the code.** When a user clicks the call to action, your app calls [**/oauth/device/code**](/reference/authentication-devices/code) to generate new codes. In your UI, display the `user_code` and instruct the user to visit the `verification_url` on their computer or mobile device. The `user_code` is typically 8 characters, so make sure there is enough room to display the full code. 3. **Authorizing your app.** When the user visits the `verification_url` it first checks to make sure they're signed in. If not signed in, they'll be able to or can sign up for a new account. After entering the code, the user will be prompted to grant permission for your app. Once approved, the user will see a success message indicating their device is connected. 4. **Confirm successful authorization.** Your app will be polling to see if the user successfully authorizes your app. Once they have, refresh your UI to indicate a successful connection has been made. ## Device Code [/oauth/device/code] ### Generate new device codes [POST] 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. | + Request (application/json) + Body { "client_id": "9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f" } + Response 200 (application/json) + Body { "device_code": "d9c126a7706328d808914cfd1e40274b6e009f684b1aca271b9b3f90b3630d64", "user_code": "5055CC52", "verification_url": "https://trakt.tv/activate", "expires_in": 600, "interval": 5 } ## Get Token [/oauth/device/token] ### Poll for the access_token [POST] 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* + Request (application/json) + Body { "code": "fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0", "client_id": "9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret": "d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2" } + Response 200 (application/json) + Body { "access_token": "dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781", "token_type": "bearer", "expires_in": 86400, "refresh_token": "76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c", "scope": "public", "created_at": 1487889741 } # Group Calendars By default, the calendar will return all shows or movies for the specified time period and can be global or user specific. The `start_date` defaults to today and `days` to 7. The maximum amount of `days` you can send is `33`. All dates (including the `start_date` and `first_aired`) are in UTC, so it's up to your app to handle any offsets based on the user's time zone. The `my` calendar displays episodes for all shows that have been watched, or watchlisted plus individual episodes on the watchlist. It will remove any shows that have been hidden from the calendar. The `all` calendar displays info for all shows airing during the specified period. ## My Shows [/calendars/my/shows/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get shows [GET] #### 🔒 OAuth Required ✨ Extended Info 🎚 Filters Returns all shows airing during the time period specified. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-07-14T01:00:00.000Z", "episode": { "season": 7, "number": 4, "title": "Death is Not the End", "ids": { "trakt": 443, "tvdb": 4851180, "imdb": "tt3500614", "tmdb": 988123 } }, "show": { "title": "True Blood", "year": 2008, "ids": { "trakt": 5, "slug": "true-blood", "tvdb": 82283, "imdb": "tt0844441", "tmdb": 10545 } } }, { "first_aired": "2014-07-14T02:00:00.000Z", "episode": { "season": 1, "number": 3, "title": "Two Boats and a Helicopter", "ids": { "trakt": 499, "tvdb": 4854797, "imdb": "tt3631218", "tmdb": 988346 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } }, { "first_aired": "2014-07-21T01:00:00.000Z", "episode": { "season": 7, "number": 5, "title": "Return to Oz", "ids": { "trakt": 444, "tvdb": 4851181, "imdb": "tt3500616", "tmdb": 988124 } }, "show": { "title": "True Blood", "year": 2008, "ids": { "trakt": 5, "slug": "true-blood", "tvdb": 82283, "imdb": "tt0844441", "tmdb": 10545 } } }, { "first_aired": "2014-07-21T02:00:00.000Z", "episode": { "season": 1, "number": 4, "title": "B.J. and the A.C.", "ids": { "trakt": 500, "tvdb": 4854798, "imdb": "tt3594942", "tmdb": 988347 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } } ] ## My New Shows [/calendars/my/shows/new/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get new shows [GET] #### 🔒 OAuth Required ✨ Extended Info 🎚 Filters Returns all new show premieres (`series_premiere`) airing during the time period specified. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-06-30T02:00:00.000Z", "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 497, "tvdb": null, "imdb": "tt3203968", "tmdb": 983732 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } } ] ## My Season Premieres [/calendars/my/shows/premieres/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get season premieres [GET] #### 🔒 OAuth Required ✨ Extended Info 🎚 Filters Returns all show premieres (`mid_season_premiere`, `season_premiere`, `series_premiere`) airing during the time period specified. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-06-30T02:00:00.000Z", "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 497, "tvdb": null, "imdb": "tt3203968", "tmdb": 983732 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } }, { "first_aired": "2014-10-13T01:00:00.000Z", "episode": { "season": 5, "number": 1, "title": "5x1", "ids": { "trakt": 163, "tvdb": null, "imdb": "", "tmdb": 975949 } }, "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## My Finales [/calendars/my/shows/finales/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get finales [GET] #### 🔒 OAuth Required ✨ Extended Info 🎚 Filters Returns all show finales (`mid_season_finale`, `season_finale`, `series_finale`) airing during the time period specified. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-06-30T02:00:00.000Z", "episode": { "season": 1, "number": 10, "title": "Season Finale", "ids": { "trakt": 497, "tvdb": null, "imdb": "tt3203968", "tmdb": 983732 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } }, { "first_aired": "2014-10-13T01:00:00.000Z", "episode": { "season": 5, "number": 10, "title": "5x10", "ids": { "trakt": 163, "tvdb": null, "imdb": "", "tmdb": 975949 } }, "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## My Movies [/calendars/my/movies/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get movies [GET] #### 🔒 OAuth Required ✨ Extended Info 🎚 Filters Returns all movies with a release date during the time period specified. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "released": "2014-08-01", "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "released": "2014-08-01", "movie": { "title": "Get On Up", "year": 2014, "ids": { "trakt": 29, "slug": "get-on-up-2014", "imdb": "tt2473602", "tmdb": 239566 } } }, { "released": "2014-08-08", "movie": { "title": "Teenage Mutant Ninja Turtles", "year": 2014, "ids": { "trakt": 30, "slug": "teenage-mutant-ninja-turtles-2014", "imdb": "tt1291150", "tmdb": 98566 } } } ] ## My Streaming [/calendars/my/streaming/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get streaming releases [GET] #### 🔒 OAuth Required ✨ Extended Info 🎚 Filters Returns all movies with a `us` streaming release date during the time period specified. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "released": "2014-08-01", "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "released": "2014-08-01", "movie": { "title": "Get On Up", "year": 2014, "ids": { "trakt": 29, "slug": "get-on-up-2014", "imdb": "tt2473602", "tmdb": 239566 } } }, { "released": "2014-08-08", "movie": { "title": "Teenage Mutant Ninja Turtles", "year": 2014, "ids": { "trakt": 30, "slug": "teenage-mutant-ninja-turtles-2014", "imdb": "tt1291150", "tmdb": 98566 } } } ] ## My DVD [/calendars/my/dvd/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get DVD releases [GET] #### 🔒 OAuth Required ✨ Extended Info 🎚 Filters Returns all movies with a `us` DVD release date during the time period specified. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "released": "2014-08-01", "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "released": "2014-08-01", "movie": { "title": "Get On Up", "year": 2014, "ids": { "trakt": 29, "slug": "get-on-up-2014", "imdb": "tt2473602", "tmdb": 239566 } } }, { "released": "2014-08-08", "movie": { "title": "Teenage Mutant Ninja Turtles", "year": 2014, "ids": { "trakt": 30, "slug": "teenage-mutant-ninja-turtles-2014", "imdb": "tt1291150", "tmdb": 98566 } } } ] ## All Shows [/calendars/all/shows/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get shows [GET] #### ✨ Extended Info 🎚 Filters Returns all shows airing during the time period specified. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-07-14T01:00:00.000Z", "episode": { "season": 7, "number": 4, "title": "Death is Not the End", "ids": { "trakt": 443, "tvdb": 4851180, "imdb": "tt3500614", "tmdb": 988123 } }, "show": { "title": "True Blood", "year": 2008, "ids": { "trakt": 5, "slug": "true-blood", "tvdb": 82283, "imdb": "tt0844441", "tmdb": 10545 } } }, { "first_aired": "2014-07-14T02:00:00.000Z", "episode": { "season": 1, "number": 3, "title": "Two Boats and a Helicopter", "ids": { "trakt": 499, "tvdb": 4854797, "imdb": "tt3631218", "tmdb": 988346 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } }, { "first_aired": "2014-07-21T01:00:00.000Z", "episode": { "season": 7, "number": 5, "title": "Return to Oz", "ids": { "trakt": 444, "tvdb": 4851181, "imdb": "tt3500616", "tmdb": 988124 } }, "show": { "title": "True Blood", "year": 2008, "ids": { "trakt": 5, "slug": "true-blood", "tvdb": 82283, "imdb": "tt0844441", "tmdb": 10545 } } }, { "first_aired": "2014-07-21T02:00:00.000Z", "episode": { "season": 1, "number": 4, "title": "B.J. and the A.C.", "ids": { "trakt": 500, "tvdb": 4854798, "imdb": "tt3594942", "tmdb": 988347 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } } ] ## All New Shows [/calendars/all/shows/new/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get new shows [GET] #### ✨ Extended Info 🎚 Filters Returns all new show premieres (`series_premiere`) airing during the time period specified. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-06-30T02:00:00.000Z", "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 497, "tvdb": null, "imdb": "tt3203968", "tmdb": 983732 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } } ] ## All Season Premieres [/calendars/all/shows/premieres/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get season premieres [GET] #### ✨ Extended Info 🎚 Filters Returns all show premieres (`mid_season_premiere`, `season_premiere`, `series_premiere`) airing during the time period specified. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-06-30T02:00:00.000Z", "episode": { "season": 1, "number": 10, "title": "Season Finale", "ids": { "trakt": 497, "tvdb": null, "imdb": "tt3203968", "tmdb": 983732 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } }, { "first_aired": "2014-10-13T01:00:00.000Z", "episode": { "season": 5, "number": 10, "title": "5x10", "ids": { "trakt": 163, "tvdb": null, "imdb": "", "tmdb": 975949 } }, "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## All Finales [/calendars/all/shows/finales/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get finales [GET] #### ✨ Extended Info 🎚 Filters Returns all show finales (`mid_season_finale`, `season_finale`, `series_finale`) airing during the time period specified. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "first_aired": "2014-06-30T02:00:00.000Z", "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 497, "tvdb": null, "imdb": "tt3203968", "tmdb": 983732 } }, "show": { "title": "The Leftovers", "year": 2014, "ids": { "trakt": 7, "slug": "the-leftovers", "tvdb": 269689, "imdb": "tt2699128", "tmdb": 54344 } } }, { "first_aired": "2014-10-13T01:00:00.000Z", "episode": { "season": 5, "number": 1, "title": "5x1", "ids": { "trakt": 163, "tvdb": null, "imdb": "", "tmdb": 975949 } }, "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## All Movies [/calendars/all/movies/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get movies [GET] #### ✨ Extended Info 🎚 Filters Returns all movies with a release date during the time period specified. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "released": "2014-08-01", "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "released": "2014-08-01", "movie": { "title": "Get On Up", "year": 2014, "ids": { "trakt": 29, "slug": "get-on-up-2014", "imdb": "tt2473602", "tmdb": 239566 } } }, { "released": "2014-08-08", "movie": { "title": "Teenage Mutant Ninja Turtles", "year": 2014, "ids": { "trakt": 30, "slug": "teenage-mutant-ninja-turtles-2014", "imdb": "tt1291150", "tmdb": 98566 } } } ] ## All Streaming [/calendars/all/streaming/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get streaming releases [GET] #### ✨ Extended Info 🎚 Filters Returns all movies with a `us` streaming release date during the time period specified. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "released": "2014-08-01", "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "released": "2014-08-01", "movie": { "title": "Get On Up", "year": 2014, "ids": { "trakt": 29, "slug": "get-on-up-2014", "imdb": "tt2473602", "tmdb": 239566 } } }, { "released": "2014-08-08", "movie": { "title": "Teenage Mutant Ninja Turtles", "year": 2014, "ids": { "trakt": 30, "slug": "teenage-mutant-ninja-turtles-2014", "imdb": "tt1291150", "tmdb": 98566 } } } ] ## All DVD [/calendars/all/dvd/{start_date}/{days}] + Parameters + start_date (optional, string, `2014-09-01`) ... Start the calendar on this date. + days (optional, integer, `7`) ... Number of days to display. ### Get DVD releases [GET] #### ✨ Extended Info 🎚 Filters Returns all movies with a `us` DVD release date during the time period specified. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: Tue, 08 Mar 2016 00:00:00 GMT X-End-Date: Mon, 14 Mar 2016 23:59:59 GMT + Body [ { "released": "2014-08-01", "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "released": "2014-08-01", "movie": { "title": "Get On Up", "year": 2014, "ids": { "trakt": 29, "slug": "get-on-up-2014", "imdb": "tt2473602", "tmdb": 239566 } } }, { "released": "2014-08-08", "movie": { "title": "Teenage Mutant Ninja Turtles", "year": 2014, "ids": { "trakt": 30, "slug": "teenage-mutant-ninja-turtles-2014", "imdb": "tt1291150", "tmdb": 98566 } } } ] # Group Checkin Checking in is a manual action used by mobile apps allowing the user to indicate what they are watching right now. While not as effortless as scrobbling, checkins help fill in the gaps. You might be watching live tv, at a friend's house, or watching a movie in theaters. You can simply checkin from your phone or tablet in those situations. The item will display as *watching* on the site, then automatically switch to *watched* status once the duration has elapsed. ## Checkin [/checkin] ### Check into an item [POST] #### 🔒 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 | > ### 🅽🅾🆃🅴 > _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._ + Request (application/json) Movie checkin by sending a standard `movie` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } }, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "message": "Guardians of the Galaxy FTW!" } + Response 201 (application/json) + Body { "id": 3373536619, "watched_at": "2014-08-06T01:11:37.000Z", "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } } + Request (application/json) Episode checkin by sending a standard `episode` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "episode": { "ids": { "trakt": 16 } }, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "message": "I'm the one who knocks!" } + Response 201 (application/json) + Body { "id": 3373536620, "watched_at": "2014-08-06T06:54:36.859Z", "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 16, "tvdb": 349232, "imdb": "tt0959621", "tmdb": 62085 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } + Request (application/json) Episode checkin if you don't have episode ids, but have show info. Send `show` and `episode` objects. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "tvdb": 81189 } }, "episode": { "season": 1, "number": 1 }, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "message": "I'm the one who knocks!" } + Response 201 (application/json) + Body { "id": 3373536621, "watched_at": "2014-08-06T06:54:36.859Z", "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 16, "tvdb": 349232, "imdb": "tt0959621", "tmdb": 62085 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } + Request (application/json) Episode checkin using absolute numbering (useful for Anime and Donghua). Send `show` and `episode` objects. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "One Piece", "year": 1999, "ids": { "trakt": 37696 } }, "episode": { "number_abs": 164 }, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "message": "I'm the one who lights the fire!" } + Response 201 (application/json) + Body { "id": 3373536622, "watched_at": "2019-01-20T06:54:36.859Z", "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 9, "number": 21, "title": "Light the Fire of Shandia! Wiper the Warrior", "ids": { "trakt": 856373, "tvdb": 362082, "imdb": null, "tmdb": null } }, "show": { "title": "One Piece", "year": 1999, "ids": { "trakt": 37696, "slug": "one-piece", "tvdb": 81797, "imdb": "tt0388629", "tmdb": 37854 } } } + Response 409 (application/json) There is already a checkin in progress. + Body { "expires_at": "2014-10-15T22:21:29.000Z" } ### Delete any active checkins [DELETE] #### 🔒 OAuth Required Removes any active checkins, no need to provide a specific item. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 # Group Certifications ## List [/certifications/{type}] Most TV shows and movies have a certification to indicate the content rating. Some API methods allow filtering by certification, so it's good to cache this list in your app. > ### 🅽🅾🆃🅴 > _Only `us` certifications are currently returned._ + Parameters + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get certifications [GET] Get a list of all certifications, including names, slugs, and descriptions. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "us": [ { "name": "G", "slug": "g", "description": "All Ages" }, { "name": "PG", "slug": "pg", "description": "Parental Guidance Suggested" }, { "name": "PG-13", "slug": "pg-13", "description": "Parents Strongly Cautioned - Ages 13+ Recommended" }, { "name": "R", "slug": "r", "description": "Mature Audiences - Ages 17+ Recommended" }, { "name": "Not Rated", "slug": "nr", "description": "Not Rated" } ] } # Group Comments Comments are attached to any movie, show, season, episode, or list and can be a quick shout or a more detailed review. Each comment can have replies and can be liked. These likes are used to determine popular comments. Comments must follow these rules and your app should indicate these to the user. Failure to adhere to these rules could suspend the user's commenting abilities. - Comments must be at least 5 words. - Comments 200 words or longer will be automatically marked as a review. - Correctly indicate if the comment contains spoilers. - Only write comments in English - **This is important!** - **Do not include** app specific text like (via App Name) or #apphashtag. This clutters up the comments and failure to clean the comment text could get your app blacklisted from commenting. #### Possible Error Responses | Code | Description | |---|---| | `401` | Invalid user | `401` | User banned from commenting | `404` | Item not found or doesn't allow comments | `409` | Comment can't be deleted | `422` | Validation errors #### Validation Errors If a comment doesn't pass validation, it returns a `422` HTTP error code and an array of validation errors in the response. The validation errors could include: | Error Message | |---| | `must be at least 5 words` | | `must be written in English` | #### Comment Formatting Comments support [**markdown**](https://en.wikipedia.org/wiki/Markdown) formatting so you'll want to render this in your app so it matches what the website does. In addition, we support inline spoiler tags like `[spoiler]text[/spoiler]` which you should also handle independent of the top level `spoiler` attribute. ## Comments [/comments] ### Post a comment [POST] #### 🔒 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 | + Request (application/json) Movie comment by sending a standard `movie` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } }, "comment": "Oh, I wasn't really listening.", "spoiler": false, "sharing": { "twitter": true, "tumblr": false, "medium": true } } + Response 201 (application/json) + Body { "id": 190, "parent_id": 0, "created_at": "2014-08-04T06:46:01.000Z", "updated_at": "2014-08-04T06:46:01.000Z", "comment": "Oh, I wasn't really listening.", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } }, "sharing": { "twitter": true, "tumblr": false, "medium": true } } + Request (application/json) Show comment by sending a standard `show` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "Breaking Bad", "ids": { "trakt": 1, "slug": "breaking-bad" } }, "comment": "Welcome to Pollos Hermanos.", "spoiler": false } + Response 201 (application/json) + Body { "id": 190, "parent_id": 0, "created_at": "2014-08-04T06:46:01.000Z", "updated_at": "2014-08-04T06:46:01.000Z", "comment": "Welcome to Pollos Hermanos.", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } + Request (application/json) Season comment by sending a standard `season` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "season": { "ids": { "trakt": 16 } }, "comment": "Hello Gus.", "spoiler": false } + Response 201 (application/json) + Body { "id": 190, "parent_id": 0, "created_at": "2014-08-04T06:46:01.000Z", "updated_at": "2014-08-04T06:46:01.000Z", "comment": "Hello Gus.", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) Episode comment by sending a standard `episode` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "episode": { "ids": { "trakt": 16 } }, "comment": "I am the danger!", "spoiler": false } + Response 201 (application/json) + Body { "id": 190, "parent_id": 0, "created_at": "2014-08-04T06:46:01.000Z", "updated_at": "2014-08-04T06:46:01.000Z", "comment": "I am the danger!", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) List comment by sending a standard `list` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "list": { "ids": { "trakt": 16 } }, "comment": "I want candy.", "spoiler": false } + Response 201 (application/json) + Body { "id": 190, "parent_id": 0, "created_at": "2014-08-04T06:46:01.000Z", "updated_at": "2014-08-04T06:46:01.000Z", "comment": "I want candy.", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ## Comment [/comments/{id}] + Parameters + id (required, integer, `417`) ... A specific comment ID. ### Get a comment or reply [GET] #### 😁 Emojis Returns a single comment and indicates how many replies it has. Use [**/comments/:id/replies**](/reference/comments/replies/) to get the actual replies. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Item-ID: 1337 X-Item-Type: show + Body { "id": 1, "parent_id": 0, "created_at": "2010-11-03T06:30:13.000Z", "comment": "Agreed, this show is awesome. AMC in general has awesome shows.", "spoiler": false, "review": false, "replies": 1, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ### Update a comment or reply [PUT] #### 🔒 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? | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "comment": "Agreed, this show is awesome. AMC in general has awesome shows and I can't wait to see what they come up with next.", "spoiler": false } + Response 200 (application/json) + Body { "id": 1, "parent_id": 0, "created_at": "2010-11-03T06:30:13.000Z", "updated_at": "2010-11-13T06:30:13.000Z", "comment": "Agreed, this show is awesome. AMC in general has awesome shows and I can't wait to see what they come up with next.", "spoiler": false, "review": false, "replies": 1, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ### Delete a comment or reply [DELETE] #### 🔒 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 ## Replies [/comments/{id}/replies] + Parameters + id (required, integer, `417`) ... A specific comment ID. ### Get replies for a comment [GET] #### 🔓 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`. > ### 🅽🅾🆃🅴 > _If you send OAuth, replies from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 19, "parent_id": 1, "created_at": "2014-07-27T23:06:59.000Z", "updated_at": "2014-07-27T23:06:59.000Z", "comment": "Season 2 has really picked up the action!", "spoiler": true, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ### Post a reply for a comment [POST] #### 🔒 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. > ### 🅽🅾🆃🅴 > 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? | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "comment": "Couldn't agree more with your review!", "spoiler": false } + Response 201 (application/json) + Body { "id": 2, "parent_id": 1, "created_at": "2014-09-01T06:30:13.000Z", "updated_at": "2014-09-01T06:30:13.000Z", "comment": "Couldn't agree more with your review!", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ## Item [/comments/{id}/item] + Parameters + id (required, integer, `417`) ... A specific comment ID. ### Get the attached media item [GET] #### ✨ 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "type": "show", "show": { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 353, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } } } ## Likes [/comments/{id}/likes] + Parameters + id (required, integer, `417`) ... A specific comment ID. ### Get all users who liked a comment [GET] #### 📄 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "liked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, { "liked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## Like [/comments/{id}/like] + Parameters + id (required, integer, `417`) ... A specific comment ID. ### Like a comment [POST] #### 🔒 OAuth Required Votes help determine popular comments. Only one like is allowed per comment per user. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ### Remove like on a comment [DELETE] #### 🔒 OAuth Required Remove a like on a comment. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 ## Report [/comments/{id}/report] + Parameters + id (required, integer, `417`) ... A specific comment ID. ### Report a comment [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "abusive", "message": "This comment is attacking other users." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: spoilers, language, abusive, spam, bigotry, political, offtopic, support, duplicate, too_short, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } ## Trending [/comments/trending/{comment_type}/{type}{?include_replies}] + Parameters + comment_type (optional, string, `all`) ... + Values + `all` + `reviews` + `shouts` + type (optional, string, `all`) ... + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + `lists` + include_replies (optional, string, `false`) ... include comment replies ### Get trending comments [GET] #### 📄 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "comment": { "id": 267, "comment": "Great kickoff to a new Batman trilogy!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-25T00:14:57.000Z", "updated_at": "2015-04-25T00:14:57.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "comment": { "id": 199, "comment": "Skyler, I AM THE DANGER.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-02-18T06:02:30.000Z", "updated_at": "2015-02-18T06:02:30.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "season", "season": { "number": 1, "ids": { "trakt": 3958, "tvdb": 274431, "tmdb": 60394 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 220, "comment": "Kicking off season 1 for a new Batman show.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T06:53:25.000Z", "updated_at": "2015-04-21T06:53:25.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "episode", "episode": { "season": 1, "number": 1, "title": "Jim Gordon", "ids": { "trakt": 63958, "tvdb": 4768720, "imdb": "tt3216414", "tmdb": 975968 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 229, "comment": "Is this the OC?", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T15:42:31.000Z", "updated_at": "2015-04-21T15:42:31.000Z", "replies": 1, "likes": 0, "user_stats": { "rating": 7, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "list", "list": { "name": "Star Wars", "description": "The complete Star Wars saga!", "privacy": "public", "share_link": "https://trakt.tv/lists/51", "display_numbers": false, "allow_comments": true, "updated_at": "2015-04-22T22:01:39.000Z", "item_count": 8, "comment_count": 0, "likes": 0, "ids": { "trakt": 51, "slug": "star-wars" } }, "comment": { "id": 268, "comment": "May the 4th be with you!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2014-12-08T17:34:51.000Z", "updated_at": "2014-12-08T17:34:51.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } } ] ## Recent [/comments/recent/{comment_type}/{type}{?include_replies}] + Parameters + comment_type (optional, string, `all`) ... + Values + `all` + `reviews` + `shouts` + type (optional, string, `all`) ... + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + `lists` + include_replies (optional, string, `false`) ... include comment replies ### Get recently created comments [GET] #### 📄 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "comment": { "id": 267, "comment": "Great kickoff to a new Batman trilogy!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-25T00:14:57.000Z", "updated_at": "2015-04-25T00:14:57.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "comment": { "id": 199, "comment": "Skyler, I AM THE DANGER.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-02-18T06:02:30.000Z", "updated_at": "2015-02-18T06:02:30.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "season", "season": { "number": 1, "ids": { "trakt": 3958, "tvdb": 274431, "tmdb": 60394 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 220, "comment": "Kicking off season 1 for a new Batman show.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T06:53:25.000Z", "updated_at": "2015-04-21T06:53:25.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "episode", "episode": { "season": 1, "number": 1, "title": "Jim Gordon", "ids": { "trakt": 63958, "tvdb": 4768720, "imdb": "tt3216414", "tmdb": 975968 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 229, "comment": "Is this the OC?", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T15:42:31.000Z", "updated_at": "2015-04-21T15:42:31.000Z", "replies": 1, "likes": 0, "user_stats": { "rating": 7, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "list", "list": { "name": "Star Wars", "description": "The complete Star Wars saga!", "privacy": "public", "share_link": "https://trakt.tv/lists/51", "display_numbers": false, "allow_comments": true, "updated_at": "2015-04-22T22:01:39.000Z", "item_count": 8, "comment_count": 0, "likes": 0, "ids": { "trakt": 51, "slug": "star-wars" } }, "comment": { "id": 268, "comment": "May the 4th be with you!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2014-12-08T17:34:51.000Z", "updated_at": "2014-12-08T17:34:51.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } } ] ## Updates [/comments/updates/{comment_type}/{type}{?include_replies}] + Parameters + comment_type (optional, string, `all`) ... + Values + `all` + `reviews` + `shouts` + type (optional, string, `all`) ... + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + `lists` + include_replies (optional, string, `false`) ... include comment replies ### Get recently updated comments [GET] #### 📄 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "comment": { "id": 267, "comment": "Great kickoff to a new Batman trilogy!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-25T00:14:57.000Z", "updated_at": "2015-04-25T00:14:57.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "comment": { "id": 199, "comment": "Skyler, I AM THE DANGER.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-02-18T06:02:30.000Z", "updated_at": "2015-02-18T06:02:30.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "season", "season": { "number": 1, "ids": { "trakt": 3958, "tvdb": 274431, "tmdb": 60394 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 220, "comment": "Kicking off season 1 for a new Batman show.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T06:53:25.000Z", "updated_at": "2015-04-21T06:53:25.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "episode", "episode": { "season": 1, "number": 1, "title": "Jim Gordon", "ids": { "trakt": 63958, "tvdb": 4768720, "imdb": "tt3216414", "tmdb": 975968 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 229, "comment": "Is this the OC?", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T15:42:31.000Z", "updated_at": "2015-04-21T15:42:31.000Z", "replies": 1, "likes": 0, "user_stats": { "rating": 7, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "list", "list": { "name": "Star Wars", "description": "The complete Star Wars saga!", "privacy": "public", "share_link": "https://trakt.tv/lists/51", "display_numbers": false, "allow_comments": true, "updated_at": "2015-04-22T22:01:39.000Z", "item_count": 8, "comment_count": 0, "likes": 0, "ids": { "trakt": 51, "slug": "star-wars" } }, "comment": { "id": 268, "comment": "May the 4th be with you!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2014-12-08T17:34:51.000Z", "updated_at": "2014-12-08T17:34:51.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } } ] # Group Countries ## List [/countries/{type}] Some API methods allow filtering by country code, so it's good to cache this list in your app. + Parameters + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get countries [GET] Get a list of all countries, including names and codes. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "name": "Australia", "code": "au" }, { "name": "Japan", "code": "ja" }, { "name": "United States", "code": "us" } ] # Group Genres ## List [/genres/{type}] One or more genres are attached to all movies and shows. Some API methods allow filtering by genre, so it's good to cache this list in your app. + Parameters + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get genres [GET] 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /genres/movies ``` + Body [ { "name": "Action", "slug": "action" }, { "name": "Adventure", "slug": "adventure" }, { "name": "Animation", "slug": "animation" }, { "name": "Anime", "slug": "anime" }, { "name": "Comedy", "slug": "comedy" }, { "name": "Crime", "slug": "crime" }, { "name": "Disaster", "slug": "disaster" }, { "name": "Documentary", "slug": "documentary" }, { "name": "donghua", "slug": "Donghua" }, { "name": "Drama", "slug": "drama" }, { "name": "Eastern", "slug": "eastern" }, { "name": "Family", "slug": "family" }, { "name": "Fan Film", "slug": "fan-film" }, { "name": "Fantasy", "slug": "fantasy" }, { "name": "Film Noir", "slug": "film-noir" }, { "name": "History", "slug": "history" }, { "name": "Holiday", "slug": "holiday" }, { "name": "Horror", "slug": "horror" }, { "name": "Indie", "slug": "indie" }, { "name": "Music", "slug": "music" }, { "name": "Musical", "slug": "musical" }, { "name": "Mystery", "slug": "mystery" }, { "name": "None", "slug": "none" }, { "name": "Road", "slug": "road" }, { "name": "Romance", "slug": "romance" }, { "name": "Science Fiction", "slug": "science-fiction" }, { "name": "Short", "slug": "short" }, { "name": "Sports", "slug": "sports" }, { "name": "Sporting Event", "slug": "sporting-event" }, { "name": "Suspense", "slug": "suspense" }, { "name": "Thriller", "slug": "thriller" }, { "name": "Tv Movie", "slug": "tv-movie" }, { "name": "War", "slug": "war" }, { "name": "Western", "slug": "western" } ] + Response 200 (application/json) ``` /genres/movies?extended=subgenres ``` + Body [ { "name": "Action", "slug": "action", "subgenres": [ { "name": "Action Comedy", "slug": "action-comedy" }, { "name": "Heist", "slug": "heist" }, { "name": "Revenge", "slug": "revenge" }, { "name": "Martial Arts", "slug": "martial-arts" }, { "name": "Buddy Cop", "slug": "buddy-cop" }, { "name": "Spy Thriller", "slug": "spy-thriller" }, { "name": "Vigilante", "slug": "vigilante" }, { "name": "Assassin", "slug": "assassin" }, { "name": "Chase", "slug": "chase" }, { "name": "Manhunt", "slug": "manhunt" }, { "name": "Vigilante Justice", "slug": "vigilante-justice" }, { "name": "Bounty Hunter", "slug": "bounty-hunter" }, { "name": "Gunfight", "slug": "gunfight" }, { "name": "One Man Army", "slug": "one-man-army" }, { "name": "Undercover Agent", "slug": "undercover-agent" }, { "name": "Heroic Bloodshed", "slug": "heroic-bloodshed" }, { "name": "Sword And Sandal", "slug": "sword-and-sandal" } ] }, { "name": "Adventure", "slug": "adventure", "subgenres": [ { "name": "Epic Quest", "slug": "epic-quest" }, { "name": "Epic", "slug": "epic" }, { "name": "Fantasy Adventure", "slug": "fantasy-adventure" }, { "name": "Treasure Hunt", "slug": "treasure-hunt" }, { "name": "Children's Adventure", "slug": "children-s-adventure" }, { "name": "Jungle Adventure", "slug": "jungle-adventure" }, { "name": "Quest", "slug": "quest" }, { "name": "Survival", "slug": "survival" }, { "name": "Expedition", "slug": "expedition" }, { "name": "Lost Civilization", "slug": "lost-civilization" }, { "name": "Pulp Adventure", "slug": "pulp-adventure" }, { "name": "Sea Adventure", "slug": "sea-adventure" }, { "name": "Travel Adventure", "slug": "travel-adventure" }, { "name": "Exploration", "slug": "exploration" }, { "name": "Urban Adventure", "slug": "urban-adventure" } ] }, { "name": "Animation", "slug": "animation", "subgenres": [ { "name": "3d Animation", "slug": "3d-animation" }, { "name": "Adult Animation", "slug": "adult-animation" }, { "name": "Adult Cartoon", "slug": "adult-cartoon" }, { "name": "Animated Comedy", "slug": "animated-comedy" }, { "name": "Classic Cartoon", "slug": "classic-cartoon" }, { "name": "Hand Drawn Animation", "slug": "hand-drawn-animation" }, { "name": "Stop Motion", "slug": "stop-motion" }, { "name": "Animal Animation", "slug": "animal-animation" }, { "name": "Western Animation", "slug": "western-animation" }, { "name": "Live Action And Animation", "slug": "live-action-and-animation" }, { "name": "Puppet Animation", "slug": "puppet-animation" }, { "name": "Psychedelic Animation", "slug": "psychedelic-animation" } ] }, { "name": "Anime", "slug": "anime", "subgenres": [ { "name": "Isekai", "slug": "isekai" }, { "name": "Magical Girl", "slug": "magical-girl" }, { "name": "Mecha", "slug": "mecha" }, { "name": "Shounen", "slug": "shounen" }, { "name": "Cyberpunk", "slug": "cyberpunk" }, { "name": "Historical Anime", "slug": "historical-anime" }, { "name": "Shoujo", "slug": "shoujo" }, { "name": "Shounen Ai", "slug": "shounen-ai" }, { "name": "Slice Of Life", "slug": "slice-of-life" }, { "name": "Yuri", "slug": "yuri" }, { "name": "Reverse Isekai", "slug": "reverse-isekai" }, { "name": "Seinen", "slug": "seinen" }, { "name": "Wuxia", "slug": "wuxia" }, { "name": "Chanbara", "slug": "chanbara" } ] }, { "name": "Comedy", "slug": "comedy", "subgenres": [ { "name": "Dark Comedy", "slug": "dark-comedy" }, { "name": "Romantic Comedy", "slug": "romantic-comedy" }, { "name": "Action Comedy", "slug": "action-comedy" }, { "name": "Dramedy", "slug": "dramedy" }, { "name": "Absurdist Comedy", "slug": "absurdist-comedy" }, { "name": "Buddy Comedy", "slug": "buddy-comedy" }, { "name": "Mockumentary", "slug": "mockumentary" }, { "name": "Parody", "slug": "parody" }, { "name": "Satire", "slug": "satire" }, { "name": "Crime Comedy", "slug": "crime-comedy" }, { "name": "Cringe Comedy", "slug": "cringe-comedy" }, { "name": "Heist Comedy", "slug": "heist-comedy" }, { "name": "Slapstick Comedy", "slug": "slapstick-comedy" }, { "name": "Stoner Comedy", "slug": "stoner-comedy" }, { "name": "Workplace Comedy", "slug": "workplace-comedy" } ] }, { "name": "Crime", "slug": "crime", "subgenres": [ { "name": "Detective", "slug": "detective" }, { "name": "Heist", "slug": "heist" }, { "name": "Police Procedural", "slug": "police-procedural" }, { "name": "Gangster", "slug": "gangster" }, { "name": "Mafia", "slug": "mafia" }, { "name": "Organized Crime", "slug": "organized-crime" }, { "name": "Serial Killer", "slug": "serial-killer" }, { "name": "Con Artist", "slug": "con-artist" }, { "name": "Crime Saga", "slug": "crime-saga" }, { "name": "True Crime", "slug": "true-crime" }, { "name": "Undercover", "slug": "undercover" }, { "name": "Caper", "slug": "caper" }, { "name": "Corrupt Cop", "slug": "corrupt-cop" }, { "name": "Drug Cartel", "slug": "drug-cartel" }, { "name": "Mobster", "slug": "mobster" }, { "name": "Robbery", "slug": "robbery" }, { "name": "Neo Noir", "slug": "neo-noir" } ] }, { "name": "Documentary", "slug": "documentary", "subgenres": [ { "name": "True Crime", "slug": "true-crime" }, { "name": "Biographical Documentary", "slug": "biographical-documentary" }, { "name": "Crime Documentary", "slug": "crime-documentary" }, { "name": "Historical Documentary", "slug": "historical-documentary" }, { "name": "Docuseries", "slug": "docuseries" }, { "name": "Environmental Documentary", "slug": "environmental-documentary" }, { "name": "Investigative", "slug": "investigative" }, { "name": "Science Documentary", "slug": "science-documentary" }, { "name": "Art Documentary", "slug": "art-documentary" }, { "name": "Music Documentary", "slug": "music-documentary" }, { "name": "Nature Documentary", "slug": "nature-documentary" }, { "name": "Sports Documentary", "slug": "sports-documentary" }, { "name": "Travel Documentary", "slug": "travel-documentary" }, { "name": "Docudrama", "slug": "docudrama" }, { "name": "Political Documentary", "slug": "political-documentary" } ] }, { "name": "Donghua", "slug": "donghua", "subgenres": [ { "name": "Donghua", "slug": "donghua" } ] }, { "name": "Drama", "slug": "drama", "subgenres": [ { "name": "Coming Of Age", "slug": "coming-of-age" }, { "name": "Crime Drama", "slug": "crime-drama" }, { "name": "Family Drama", "slug": "family-drama" }, { "name": "Romantic Drama", "slug": "romantic-drama" }, { "name": "Melodrama", "slug": "melodrama" }, { "name": "Psychological Drama", "slug": "psychological-drama" }, { "name": "Slice Of Life", "slug": "slice-of-life" }, { "name": "Period Drama", "slug": "period-drama" }, { "name": "Political Drama", "slug": "political-drama" }, { "name": "Social Drama", "slug": "social-drama" }, { "name": "Teen Drama", "slug": "teen-drama" }, { "name": "Tragedy", "slug": "tragedy" }, { "name": "Courtroom Drama", "slug": "courtroom-drama" }, { "name": "Medical Drama", "slug": "medical-drama" }, { "name": "Sports Drama", "slug": "sports-drama" }, { "name": "Workplace", "slug": "workplace" }, { "name": "Rural Drama", "slug": "rural-drama" }, { "name": "Workplace Drama", "slug": "workplace-drama" } ] }, { "name": "Family", "slug": "family", "subgenres": [ { "name": "Family Friendly", "slug": "family-friendly" }, { "name": "Family Drama", "slug": "family-drama" }, { "name": "Parent Child Relationship", "slug": "parent-child-relationship" }, { "name": "Family Bonds", "slug": "family-bonds" }, { "name": "Family Rivalry", "slug": "family-rivalry" }, { "name": "Family Vacation", "slug": "family-vacation" }, { "name": "Sibling Relationship", "slug": "sibling-relationship" }, { "name": "Single Parent Family", "slug": "single-parent-family" }, { "name": "Sibling Rivalry", "slug": "sibling-rivalry" }, { "name": "Single Parent", "slug": "single-parent" }, { "name": "Generational", "slug": "generational" } ] }, { "name": "Fantasy", "slug": "fantasy", "subgenres": [ { "name": "High Fantasy", "slug": "high-fantasy" }, { "name": "Epic Fantasy", "slug": "epic-fantasy" }, { "name": "Fairy Tale", "slug": "fairy-tale" }, { "name": "Fantasy Adventure", "slug": "fantasy-adventure" }, { "name": "Urban Fantasy", "slug": "urban-fantasy" }, { "name": "Dark Fantasy", "slug": "dark-fantasy" }, { "name": "Magical Realism", "slug": "magical-realism" }, { "name": "Mythology", "slug": "mythology" }, { "name": "Portal Fantasy", "slug": "portal-fantasy" }, { "name": "Witch", "slug": "witch" }, { "name": "Supernatural", "slug": "supernatural" }, { "name": "Sword And Sorcery", "slug": "sword-and-sorcery" }, { "name": "Magic", "slug": "magic" } ] }, { "name": "History", "slug": "history", "subgenres": [ { "name": "Historical Drama", "slug": "historical-drama" }, { "name": "Period Piece", "slug": "period-piece" }, { "name": "Civil War", "slug": "civil-war" }, { "name": "Historical Fiction", "slug": "historical-fiction" }, { "name": "World War Ii", "slug": "world-war-ii" }, { "name": "Vietnam War", "slug": "vietnam-war" }, { "name": "Ancient History", "slug": "ancient-history" }, { "name": "Political Murder", "slug": "political-murder" } ] }, { "name": "Holiday", "slug": "holiday", "subgenres": [ { "name": "Christmas", "slug": "christmas" }, { "name": "Holiday Season", "slug": "holiday-season" }, { "name": "Christmas Party", "slug": "christmas-party" }, { "name": "Halloween", "slug": "halloween" }, { "name": "Thanksgiving", "slug": "thanksgiving" } ] }, { "name": "Horror", "slug": "horror", "subgenres": [ { "name": "Supernatural Horror", "slug": "supernatural-horror" }, { "name": "Psychological Horror", "slug": "psychological-horror" }, { "name": "Slasher", "slug": "slasher" }, { "name": "Zombie", "slug": "zombie" }, { "name": "Body Horror", "slug": "body-horror" }, { "name": "Found Footage", "slug": "found-footage" }, { "name": "Haunted House", "slug": "haunted-house" }, { "name": "Monster Movie", "slug": "monster-movie" }, { "name": "Vampire", "slug": "vampire" }, { "name": "Folk Horror", "slug": "folk-horror" }, { "name": "Home Invasion", "slug": "home-invasion" }, { "name": "Possession", "slug": "possession" }, { "name": "Revenge Horror", "slug": "revenge-horror" }, { "name": "Cosmic Horror", "slug": "cosmic-horror" }, { "name": "Creature Feature", "slug": "creature-feature" }, { "name": "Gothic Horror", "slug": "gothic-horror" }, { "name": "Giallo", "slug": "giallo" } ] }, { "name": "Music", "slug": "music", "subgenres": [ { "name": "Musical", "slug": "musical" }, { "name": "Hip Hop", "slug": "hip-hop" }, { "name": "Music Documentary", "slug": "music-documentary" }, { "name": "Concert", "slug": "concert" }, { "name": "Concert Film", "slug": "concert-film" }, { "name": "Rock Star", "slug": "rock-star" }, { "name": "Live Concert", "slug": "live-concert" }, { "name": "Music Video", "slug": "music-video" }, { "name": "Pop Song", "slug": "pop-song" }, { "name": "Rock", "slug": "rock" }, { "name": "Jazz Fusion", "slug": "jazz-fusion" }, { "name": "Pop", "slug": "pop" } ] }, { "name": "Musical", "slug": "musical", "subgenres": [ { "name": "Musical Comedy", "slug": "musical-comedy" }, { "name": "Movie Musical", "slug": "movie-musical" }, { "name": "Musical Drama", "slug": "musical-drama" }, { "name": "Integrated Musical", "slug": "integrated-musical" }, { "name": "Jukebox Musical", "slug": "jukebox-musical" }, { "name": "Rock Opera", "slug": "rock-opera" }, { "name": "Romance Musical", "slug": "romance-musical" }, { "name": "Dance Film", "slug": "dance-film" }, { "name": "Original Musical", "slug": "original-musical" }, { "name": "Stage Musical", "slug": "stage-musical" } ] }, { "name": "Mystery", "slug": "mystery", "subgenres": [ { "name": "Murder Mystery", "slug": "murder-mystery" }, { "name": "Whodunit", "slug": "whodunit" }, { "name": "Amateur Detective", "slug": "amateur-detective" }, { "name": "Detective", "slug": "detective" }, { "name": "Psychological Thriller", "slug": "psychological-thriller" }, { "name": "Film Noir", "slug": "film-noir" }, { "name": "Mystery Thriller", "slug": "mystery-thriller" }, { "name": "Unsolved Mystery", "slug": "unsolved-mystery" }, { "name": "Locked Room Mystery", "slug": "locked-room-mystery" }, { "name": "Unsolved Crime", "slug": "unsolved-crime" }, { "name": "Conspiracy", "slug": "conspiracy" }, { "name": "Paranormal Research", "slug": "paranormal-research" }, { "name": "Psychological Mystery", "slug": "psychological-mystery" } ] }, { "name": "None", "slug": "none", "subgenres": [] }, { "name": "Romance", "slug": "romance", "subgenres": [ { "name": "Romantic Comedy", "slug": "romantic-comedy" }, { "name": "Romantic Drama", "slug": "romantic-drama" }, { "name": "Enemies To Lovers", "slug": "enemies-to-lovers" }, { "name": "Friends To Lovers", "slug": "friends-to-lovers" }, { "name": "Forbidden Love", "slug": "forbidden-love" }, { "name": "Second Chance Romance", "slug": "second-chance-romance" }, { "name": "Slow Burn Romance", "slug": "slow-burn-romance" }, { "name": "Teen Romance", "slug": "teen-romance" }, { "name": "Tragic Romance", "slug": "tragic-romance" }, { "name": "Historical Romance", "slug": "historical-romance" }, { "name": "Holiday Romance", "slug": "holiday-romance" }, { "name": "Lgbt Romance", "slug": "lgbt-romance" }, { "name": "Office Romance", "slug": "office-romance" }, { "name": "Secret Crush", "slug": "secret-crush" }, { "name": "Erotic Romance", "slug": "erotic-romance" }, { "name": "Dark Romance", "slug": "dark-romance" } ] }, { "name": "Science Fiction", "slug": "science-fiction", "subgenres": [ { "name": "Alien Invasion", "slug": "alien-invasion" }, { "name": "Dystopian", "slug": "dystopian" }, { "name": "Cyberpunk", "slug": "cyberpunk" }, { "name": "Space Opera", "slug": "space-opera" }, { "name": "Time Travel", "slug": "time-travel" }, { "name": "Alien Encounter", "slug": "alien-encounter" }, { "name": "Mecha", "slug": "mecha" }, { "name": "Android", "slug": "android" }, { "name": "Multiverse", "slug": "multiverse" }, { "name": "Robot Apocalypse", "slug": "robot-apocalypse" }, { "name": "Simulated World", "slug": "simulated-world" }, { "name": "Space Horror", "slug": "space-horror" }, { "name": "Virtual Reality", "slug": "virtual-reality" }, { "name": "Hard Sci Fi", "slug": "hard-sci-fi" }, { "name": "Military Sci Fi", "slug": "military-sci-fi" }, { "name": "Steampunk", "slug": "steampunk" } ] }, { "name": "Short", "slug": "short", "subgenres": [ { "name": "Short Film", "slug": "short-film" }, { "name": "Animated Short", "slug": "animated-short" }, { "name": "Comedy Short Film", "slug": "comedy-short-film" }, { "name": "Documentary Short", "slug": "documentary-short" }, { "name": "Horror Short", "slug": "horror-short" }, { "name": "Student Film", "slug": "student-film" } ] }, { "name": "Sporting Event", "slug": "sporting-event", "subgenres": [] }, { "name": "Superhero", "slug": "superhero", "subgenres": [ { "name": "Superhero", "slug": "superhero" }, { "name": "Origin Story", "slug": "origin-story" }, { "name": "Supervillain", "slug": "supervillain" }, { "name": "Superhero Team", "slug": "superhero-team" }, { "name": "Masked Vigilante", "slug": "masked-vigilante" }, { "name": "Origin Of Hero", "slug": "origin-of-hero" }, { "name": "Superhero Parody", "slug": "superhero-parody" }, { "name": "Real Life Superheroes", "slug": "real-life-superheroes" } ] }, { "name": "Suspense", "slug": "suspense", "subgenres": [ { "name": "Psychological Thriller", "slug": "psychological-thriller" }, { "name": "Suspense", "slug": "suspense" }, { "name": "Domestic Thriller", "slug": "domestic-thriller" }, { "name": "Contained Thriller", "slug": "contained-thriller" }, { "name": "Paranoia", "slug": "paranoia" }, { "name": "Psychological Suspense Thriller", "slug": "psychological-suspense-thriller" }, { "name": "Slow Burn", "slug": "slow-burn" } ] }, { "name": "Thriller", "slug": "thriller", "subgenres": [ { "name": "Psychological Thriller", "slug": "psychological-thriller" }, { "name": "Action Thriller", "slug": "action-thriller" }, { "name": "Political Thriller", "slug": "political-thriller" }, { "name": "Revenge Thriller", "slug": "revenge-thriller" }, { "name": "Conspiracy Thriller", "slug": "conspiracy-thriller" }, { "name": "Mystery Thriller", "slug": "mystery-thriller" }, { "name": "Paranoid Thriller", "slug": "paranoid-thriller" }, { "name": "Spy Thriller", "slug": "spy-thriller" }, { "name": "Survival Thriller", "slug": "survival-thriller" }, { "name": "Hostage", "slug": "hostage" }, { "name": "Legal Thriller", "slug": "legal-thriller" }, { "name": "Road Thriller", "slug": "road-thriller" }, { "name": "Erotic Thriller", "slug": "erotic-thriller" } ] }, { "name": "War", "slug": "war", "subgenres": [ { "name": "War Drama", "slug": "war-drama" }, { "name": "Historical War", "slug": "historical-war" }, { "name": "World War Ii", "slug": "world-war-ii" }, { "name": "Anti War", "slug": "anti-war-bccf794e-1c7a-4665-9f5f-0e9b969a26cd" }, { "name": "Front Line Warfare", "slug": "front-line-warfare" }, { "name": "Military Drama", "slug": "military-drama" }, { "name": "War Hero", "slug": "war-hero" }, { "name": "Vietnam War", "slug": "vietnam-war" }, { "name": "War Correspondent", "slug": "war-correspondent" }, { "name": "War Crime", "slug": "war-crime" } ] }, { "name": "Western", "slug": "western", "subgenres": [ { "name": "Classic Western", "slug": "classic-western" }, { "name": "Spaghetti Western", "slug": "spaghetti-western" }, { "name": "Gunfighter", "slug": "gunfighter" }, { "name": "Outlaw", "slug": "outlaw" }, { "name": "Revisionist Western", "slug": "revisionist-western" }, { "name": "Wild West", "slug": "wild-west" }, { "name": "Frontier Western", "slug": "frontier-western" }, { "name": "Revenge Western", "slug": "revenge-western" }, { "name": "Acid Western", "slug": "acid-western" }, { "name": "Frontier", "slug": "frontier" }, { "name": "Showdown", "slug": "showdown" } ] } ] # Group Languages ## List [/languages/{type}] Some API methods allow filtering by language code, so it's good to cache this list in your app. + Parameters + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get languages [GET] Get a list of all langauges, including names and codes. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "name": "English", "code": "en" }, { "name": "Italian", "code": "it" }, { "name": "Polish", "code": "pl" } ] ## Group Lists ## Trending [/lists/trending/{type}] + Parameters + type (optional, string, `personal`) ... + Values + `personal` + `official` ### Get trending lists [GET] #### 📄 Pagination 😁 Emojis Returns all lists with the most likes and comments over the last 7 days. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "like_count": 5, "comment_count": 5, "list": { "name": "Incredible Thoughts", "description": "How could my brain conceive them?", "privacy": "public", "share_link": "https://trakt.tv/lists/1337", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 10, "likes": 99, "ids": { "trakt": 1337, "slug": "incredible-thoughts" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "like_count": 4, "comment_count": 4, "list": { "name": "Top Chihuahua Movies", "description": "So cute.", "privacy": "public", "share_link": "https://trakt.tv/lists/1338", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2015-10-11T17:00:54.000Z", "updated_at": "2015-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 20, "likes": 109, "ids": { "trakt": 1338, "slug": "top-chihuahua-movies" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } } ] ## Popular [/lists/popular/{type}] + Parameters + type (optional, string, `personal`) ... + Values + `personal` + `official` ### Get popular lists [GET] #### 📄 Pagination 😁 Emojis Returns the most popular lists. Popularity is calculated using total number of likes and comments. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "like_count": 109, "comment_count": 20, "list": { "name": "Top Chihuahua Movies", "description": "So cute.", "privacy": "public", "share_link": "https://trakt.tv/lists/1338", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2015-10-11T17:00:54.000Z", "updated_at": "2015-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 20, "likes": 109, "ids": { "trakt": 1338, "slug": "top-chihuahua-movies" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "like_count": 99, "comment_count": 10, "list": { "name": "Incredible Thoughts", "description": "How could my brain conceive them?", "privacy": "public", "share_link": "https://trakt.tv/lists/1337", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 10, "likes": 99, "ids": { "trakt": 1337, "slug": "incredible-thoughts" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } } ] ## List [/lists/{id}] + Parameters + id (required, integer, `55`) ... Trakt ID ### Get list [GET] #### 😁 Emojis Returns a single list. Use the [**/lists/:id/items**](#reference/lists/list-items) method to get the actual items this list contains. > ### 🅽🅾🆃🅴 > _You must use an integer `id`, and only public lists will return data._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body { "name": "Star Wars in machete order", "description": "Next time you want to introduce someone to Star Wars for the first time, watch the films with them in this order: IV, V, II, III, VI.", "privacy": "public", "share_link": "https://trakt.tv/lists/55", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 55, "slug": "star-wars-in-machete-order" }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ## List Likes [/lists/{id}/likes] + Parameters + id (required, string, `55`) ... Trakt ID ### Get all users who liked a list [GET] #### 📄 Pagination Returns all users who liked a list. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 X-List-ID: 1 + Body [ { "liked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, { "liked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## List Like [/lists/{id}/like] + Parameters + id (required, string, `55`) ... Trakt ID ### Like a list [POST] #### 🔒 OAuth Required Votes help determine popular lists. Only one like is allowed per list per user. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ### Remove like on a list [DELETE] #### 🔒 OAuth Required Remove a like on a list. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 ## List Items [/lists/{id}/items/{type}/{sort_by}/{sort_how}] + Parameters + id (required, string, `55`) ... Trakt ID + type (optional, string, `movies`) ... Filter for a specific item type + Values + `movie` + `show` + `season` + `episode` + `person` + sort_by (optional, string, `rank`) ... Sort by a specific property + Values + `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 (optional, string, `asc`) ... Sort direction + Values + `asc` + `desc` ### Get items on a list [GET] #### 🔥 **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. #### Notes Each list item contains a `notes` field with text entered by the user. #### Sorting Default sorting is based on the list defaults and sent in the `X-Sort-By` and `X-Sort-How` headers. If you specify the `sort_by` and `sort_how` parameters, the response will be sorted based on those values and sent in the `X-Applied-Sort-By` and `X-Applied-Sort-How` headers. Some `sort_by` options are 🔥 **VIP Only** including `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, and `tmdb_votes`. If sent for a non VIP, the items will fall back to `rank`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Private-User: false X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body [ { "rank": 1, "id": 101, "listed_at": "2014-06-16T06:07:12.000Z", "notes": null, "type": "movie", "movie": { "title": "Star Wars: Episode IV - A New Hope", "year": 1977, "ids": { "trakt": 12, "slug": "star-wars-episode-iv-a-new-hope-1977", "imdb": "tt0076759", "tmdb": 11 } } }, { "rank": 2, "id": 102, "listed_at": "2014-06-16T06:07:12.000Z", "notes": null, "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } }, { "rank": 3, "id": 103, "listed_at": "2014-06-16T06:07:12.000Z", "notes": null, "type": "season", "season": { "number": 1, "ids": { "tvdb": 30272, "tmdb": 3572 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 4, "id": 104, "listed_at": "2014-06-17T06:52:03.000Z", "notes": null, "type": "episode", "episode": { "season": 0, "number": 2, "title": "Wedding Day", "ids": { "trakt": 2, "tvdb": 3859791, "imdb": null, "tmdb": 62133 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 5, "id": 105, "listed_at": "2014-06-17T06:52:03.000Z", "notes": null, "type": "person", "person": { "name": "Garrett Hedlund", "ids": { "trakt": 1, "slug": "garrett-hedlund", "imdb": "nm1330560", "tmdb": 9828 } } } ] ## List Comments [/lists/{id}/comments/{sort}] + Parameters + id (required, integer, `55`) ... Trakt ID + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `plays` + `rating` + `added` ### Get all list comments [GET] #### 🔓 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Can't wait to watch everything on this epic list!", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## List Report [/lists/{id}/report] + Parameters + id (required, string, `official-top-250-movies-of-all-time`) ... Trakt ID or Trakt slug ### Report a list [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "spam", "message": "This list is just promoting a product." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: duplicate, remove, metadata, adult, language, spam, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } ## Group Movies ## Trending [/movies/trending] ### Get trending movies [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most watched movies over the last 24 hours. Movies with the most `watchers` are returned first. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 X-Trending-User-Count: 1721 + Body [ { "watchers": 21, "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "watchers": 17, "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] ## Popular [/movies/popular] ### Get popular movies [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most popular movies. Popularity is calculated using the rating percentage and the number of ratings. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 16, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } }, { "title": "Fight Club", "year": 1999, "ids": { "trakt": 727, "slug": "fight-club-1999", "imdb": "tt0137523", "tmdb": 550 } }, { "title": "Jurassic Park", "year": 1993, "ids": { "trakt": 393, "slug": "jurassic-park-1993", "imdb": "tt0107290", "tmdb": 329 } }, { "title": "Back to the Future", "year": 1985, "ids": { "trakt": 308, "slug": "back-to-the-future-1985", "imdb": "tt0088763", "tmdb": 105 } }, { "title": "The Shawshank Redemption", "year": 1994, "ids": { "trakt": 231, "slug": "the-shawshank-redemption-1994", "imdb": "tt0111161", "tmdb": 278 } }, { "title": "The Social Network", "year": 2010, "ids": { "trakt": 98, "slug": "the-social-network-2010", "imdb": "tt1285016", "tmdb": 37799 } }, { "title": "Star Wars: Episode IV - A New Hope", "year": 1977, "ids": { "trakt": 738, "slug": "star-wars-episode-iv-a-new-hope-1977", "imdb": "tt0076759", "tmdb": 11 } }, { "title": "The Lord of the Rings: The Return of the King", "year": 2003, "ids": { "trakt": 374, "slug": "the-lord-of-the-rings-the-return-of-the-king-2003", "imdb": "tt0167260", "tmdb": 122 } }, { "title": "The Lord of the Rings: The Two Towers", "year": 2002, "ids": { "trakt": 373, "slug": "the-lord-of-the-rings-the-two-towers-2002", "imdb": "tt0167261", "tmdb": 121 } }, { "title": "The Matrix", "year": 1999, "ids": { "trakt": 269, "slug": "the-matrix-1999", "imdb": "tt0133093", "tmdb": 603 } } ] ## Favorited [/movies/favorited/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most favorited movies [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most favorited movies in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "user_count": 76254, "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 120, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "user_count": 61289, "movie": { "title": "The Avengers", "year": 2012, "ids": { "trakt": 14701, "slug": "the-avengers-2012", "imdb": "tt0848228", "tmdb": 24428 } } }, { "user_count": 55443, "movie": { "title": "Despicable Me", "year": 2010, "ids": { "trakt": 12496, "slug": "despicable-me-2010", "imdb": "tt1323594", "tmdb": 20352 } } } ] ## Played [/movies/played/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most played movies [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most played (a single user can watch multiple times) movies in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "watcher_count": 66667, "play_count": 109736, "collected_count": 27584, "movie": { "title": "Frozen", "year": 2013, "ids": { "trakt": 77349, "slug": "frozen-2013", "imdb": "tt2294629", "tmdb": 109445 } } }, { "watcher_count": 76254, "play_count": 104242, "collected_count": 31877, "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 120, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "watcher_count": 81289, "play_count": 102512, "collected_count": 33837, "movie": { "title": "The Avengers", "year": 2012, "ids": { "trakt": 14701, "slug": "the-avengers-2012", "imdb": "tt0848228", "tmdb": 24428 } } }, { "watcher_count": 72538, "play_count": 97715, "collected_count": 26662, "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 82405, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "watcher_count": 8487, "play_count": 95830, "collected_count": 6252, "movie": { "title": "Begin Again", "year": 2014, "ids": { "trakt": 123759, "slug": "begin-again-2013", "imdb": "tt1980929", "tmdb": 198277 } } }, { "watcher_count": 74665, "play_count": 88597, "collected_count": 32044, "movie": { "title": "Inception", "year": 2010, "ids": { "trakt": 16662, "slug": "inception-2010", "imdb": "tt1375666", "tmdb": 27205 } } }, { "watcher_count": 55443, "play_count": 82227, "collected_count": 25855, "movie": { "title": "Despicable Me", "year": 2010, "ids": { "trakt": 12496, "slug": "despicable-me-2010", "imdb": "tt1323594", "tmdb": 20352 } } }, { "watcher_count": 55739, "play_count": 81167, "collected_count": 27441, "movie": { "title": "Iron Man 2", "year": 2010, "ids": { "trakt": 5355, "slug": "iron-man-2-2010", "imdb": "tt1228705", "tmdb": 10138 } } }, { "watcher_count": 45472, "play_count": 80008, "collected_count": 16419, "movie": { "title": "Big Hero 6", "year": 2014, "ids": { "trakt": 112404, "slug": "big-hero-6-2014", "imdb": "tt2245084", "tmdb": 177572 } } }, { "watcher_count": 63920, "play_count": 79998, "collected_count": 27721, "movie": { "title": "Iron Man", "year": 2008, "ids": { "trakt": 1157, "slug": "iron-man-2008", "imdb": "tt0371746", "tmdb": 1726 } } } ] ## Watched [/movies/watched/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most watched movies [GET] #### 📄 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`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "watcher_count": 81289, "play_count": 102512, "collected_count": 33837, "movie": { "title": "The Avengers", "year": 2012, "ids": { "trakt": 14701, "slug": "the-avengers-2012", "imdb": "tt0848228", "tmdb": 24428 } } }, { "watcher_count": 76254, "play_count": 104242, "collected_count": 31877, "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 120, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "watcher_count": 74665, "play_count": 88597, "collected_count": 32044, "movie": { "title": "Inception", "year": 2010, "ids": { "trakt": 16662, "slug": "inception-2010", "imdb": "tt1375666", "tmdb": 27205 } } }, { "watcher_count": 72538, "play_count": 97715, "collected_count": 26662, "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 82405, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } }, { "watcher_count": 67228, "play_count": 77108, "collected_count": 26263, "movie": { "title": "The Matrix", "year": 1999, "ids": { "trakt": 481, "slug": "the-matrix-1999", "imdb": "tt0133093", "tmdb": 603 } } }, { "watcher_count": 66667, "play_count": 109736, "collected_count": 27584, "movie": { "title": "Frozen", "year": 2013, "ids": { "trakt": 77349, "slug": "frozen-2013", "imdb": "tt2294629", "tmdb": 109445 } } }, { "watcher_count": 63920, "play_count": 79998, "collected_count": 27721, "movie": { "title": "Iron Man", "year": 2008, "ids": { "trakt": 1157, "slug": "iron-man-2008", "imdb": "tt0371746", "tmdb": 1726 } } }, { "watcher_count": 62786, "play_count": 78930, "collected_count": 27693, "movie": { "title": "Avatar", "year": 2009, "ids": { "trakt": 12269, "slug": "avatar-2009", "imdb": "tt0499549", "tmdb": 19995 } } }, { "watcher_count": 60803, "play_count": 69112, "collected_count": 27542, "movie": { "title": "The Lord of the Rings: The Fellowship of the Ring", "year": 2001, "ids": { "trakt": 88, "slug": "the-lord-of-the-rings-the-fellowship-of-the-ring-2001", "imdb": "tt0120737", "tmdb": 120 } } }, { "watcher_count": 58057, "play_count": 67884, "collected_count": 25803, "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 228, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } } } ] ## Collected [/movies/collected/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most Collected movies [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most collected (unique users) movies in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "watcher_count": 81289, "play_count": 102512, "collected_count": 33837, "movie": { "title": "The Avengers", "year": 2012, "ids": { "trakt": 14701, "slug": "the-avengers-2012", "imdb": "tt0848228", "tmdb": 24428 } } }, { "watcher_count": 74665, "play_count": 88597, "collected_count": 32044, "movie": { "title": "Inception", "year": 2010, "ids": { "trakt": 16662, "slug": "inception-2010", "imdb": "tt1375666", "tmdb": 27205 } } }, { "watcher_count": 76254, "play_count": 104242, "collected_count": 31877, "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 120, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "watcher_count": 55355, "play_count": 67402, "collected_count": 30502, "movie": { "title": "The Hobbit: An Unexpected Journey", "year": 2012, "ids": { "trakt": 34097, "slug": "the-hobbit-an-unexpected-journey-2012", "imdb": "tt0903624", "tmdb": 49051 } } }, { "watcher_count": 56916, "play_count": 71767, "collected_count": 29062, "movie": { "title": "The Dark Knight Rises", "year": 2012, "ids": { "trakt": 34073, "slug": "the-dark-knight-rises-2012", "imdb": "tt1345836", "tmdb": 49026 } } }, { "watcher_count": 57603, "play_count": 65325, "collected_count": 28037, "movie": { "title": "The Hunger Games", "year": 2012, "ids": { "trakt": 51342, "slug": "the-hunger-games-2012", "imdb": "tt1392170", "tmdb": 70160 } } }, { "watcher_count": 52662, "play_count": 63107, "collected_count": 27802, "movie": { "title": "Iron Man 3", "year": 2013, "ids": { "trakt": 50134, "slug": "iron-man-3-2013", "imdb": "tt1300854", "tmdb": 68721 } } }, { "watcher_count": 63920, "play_count": 79998, "collected_count": 27721, "movie": { "title": "Iron Man", "year": 2008, "ids": { "trakt": 1157, "slug": "iron-man-2008", "imdb": "tt0371746", "tmdb": 1726 } } }, { "watcher_count": 62786, "play_count": 78930, "collected_count": 27693, "movie": { "title": "Avatar", "year": 2009, "ids": { "trakt": 12269, "slug": "avatar-2009", "imdb": "tt0499549", "tmdb": 19995 } } }, { "watcher_count": 49809, "play_count": 60086, "collected_count": 27661, "movie": { "title": "Django Unchained", "year": 2012, "ids": { "trakt": 50131, "slug": "django-unchained-2012", "imdb": "tt1853728", "tmdb": 68718 } } } ] ## Anticipated [/movies/anticipated] ### Get the most anticipated movies [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most anticipated movies based on the number of lists a movie appears on. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "list_count": 5362, "movie": { "title": "The Hunger Games: Mockingjay - Part 2", "year": 2015, "ids": { "trakt": 89543, "slug": "the-hunger-games-mockingjay-part-2-2015", "imdb": "tt1951266", "tmdb": 131634 } } }, { "list_count": 4405, "movie": { "title": "Batman v Superman: Dawn of Justice", "year": 2016, "ids": { "trakt": 129583, "slug": "batman-v-superman-dawn-of-justice-2016", "imdb": "tt2975590", "tmdb": 209112 } } }, { "list_count": 4185, "movie": { "title": "Star Wars: Episode VII - The Force Awakens", "year": 2015, "ids": { "trakt": 94024, "slug": "star-wars-episode-vii-the-force-awakens-2015", "imdb": "tt2488496", "tmdb": 140607 } } }, { "list_count": 2996, "movie": { "title": "The Martian", "year": 2015, "ids": { "trakt": 183371, "slug": "the-martian-2015", "imdb": "tt3659388", "tmdb": 286217 } } }, { "list_count": 2902, "movie": { "title": "Deadpool", "year": 2016, "ids": { "trakt": 190430, "slug": "deadpool-2016", "imdb": "tt1431045", "tmdb": 293660 } } }, { "list_count": 2675, "movie": { "title": "Captain America: Civil War", "year": 2016, "ids": { "trakt": 169105, "slug": "captain-america-civil-war-2016", "imdb": "tt3498820", "tmdb": 271110 } } }, { "list_count": 2629, "movie": { "title": "X-Men: Apocalypse", "year": 2016, "ids": { "trakt": 149999, "slug": "x-men-apocalypse-2016", "imdb": "tt3385516", "tmdb": 246655 } } }, { "list_count": 2184, "movie": { "title": "Suicide Squad", "year": 2016, "ids": { "trakt": 193079, "slug": "suicide-squad-2016", "imdb": "tt1386697", "tmdb": 297761 } } }, { "list_count": 2127, "movie": { "title": "SPECTRE", "year": 2015, "ids": { "trakt": 128378, "slug": "spectre-2015", "imdb": "tt2379713", "tmdb": 206647 } } }, { "list_count": 1951, "movie": { "title": "Justice League", "year": 2017, "ids": { "trakt": 94232, "slug": "justice-league-2017", "imdb": "tt0974015", "tmdb": 141052 } } } ] ## Box Office [/movies/boxoffice] ### Get the weekend box office [GET] #### ✨ Extended Info Returns the top 10 grossing movies in the U.S. box office last weekend. Updated every Monday morning. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "revenue": 48464322, "movie": { "title": "Hotel Transylvania 2", "year": 2015, "ids": { "trakt": 103449, "slug": "hotel-transylvania-2-2015", "imdb": "tt2510894", "tmdb": 159824 } } }, { "revenue": 17728313, "movie": { "title": "The Intern", "year": 2015, "ids": { "trakt": 156997, "slug": "the-intern-2015", "imdb": "tt2361509", "tmdb": 257211 } } }, { "revenue": 14271777, "movie": { "title": "Maze Runner: The Scorch Trials", "year": 2015, "ids": { "trakt": 190987, "slug": "maze-runner-the-scorch-trials-2015", "imdb": "tt4046784", "tmdb": 294254 } } }, { "revenue": 13242895, "movie": { "title": "Everest", "year": 2015, "ids": { "trakt": 153969, "slug": "everest-2015", "imdb": "tt2719848", "tmdb": 253412 } } }, { "revenue": 11031215, "movie": { "title": "Black Mass", "year": 2015, "ids": { "trakt": 160067, "slug": "black-mass-2015", "imdb": "tt1355683", "tmdb": 261023 } } }, { "revenue": 6674280, "movie": { "title": "The Visit", "year": 2015, "ids": { "trakt": 196859, "slug": "the-visit-2015", "imdb": "tt3567288", "tmdb": 298312 } } }, { "revenue": 4774505, "movie": { "title": "The Perfect Guy", "year": 2015, "ids": { "trakt": 207114, "slug": "the-perfect-guy-2015", "imdb": "tt3862750", "tmdb": 304372 } } }, { "revenue": 4242644, "movie": { "title": "War Room", "year": 2015, "ids": { "trakt": 203901, "slug": "war-room", "imdb": "tt3832914", "tmdb": 323272 } } }, { "revenue": 3520626, "movie": { "title": "The Green Inferno", "year": 2014, "ids": { "trakt": 109134, "slug": "the-green-inferno-2014", "imdb": "tt2403021", "tmdb": 171424 } } }, { "revenue": 1717301, "movie": { "title": "Sicario", "year": 2015, "ids": { "trakt": 171369, "slug": "sicario-2015", "imdb": "tt3397884", "tmdb": 273481 } } } ] ## Updates [/movies/updates/{start_date}] + Parameters + start_date (optional, string, `2020-11-27T00:00:00Z`) ... Updated since this date and time. ### Get recently updated movies [GET] #### 📄 Pagination ✨ Extended Info Returns all movies updated since the specified UTC date and time. We recommended storing the `X-Start-Date` header you can be efficient using this method moving forward. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _The `start_date` is only accurate to the hour, for caching purposes. Please drop the minutes and seconds from your timestamp to help optimize our cached data. For example, use `2021-07-17T12:00:00Z` and not `2021-07-17T12:23:34Z`._ > ### 🅽🅾🆃🅴 > _The `start_date` can only be a maximum of 30 days in the past._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: 2020-11-27T00:00:00Z X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "updated_at": "2014-09-22T21:56:03.000Z", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "updated_at": "2014-09-23T21:56:03.000Z", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] ## Updated IDs [/movies/updates/id/{start_date}] + Parameters + start_date (optional, string, `2020-11-27T00:00:00Z`) ... Updated since this date and time. ### Get recently updated movie Trakt IDs [GET] #### 📄 Pagination Returns all movie Trakt IDs updated since the specified UTC date and time. We recommended storing the `X-Start-Date` header you can be efficient using this method moving forward. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _The `start_date` is only accurate to the hour, for caching purposes. Please drop the minutes and seconds from your timestamp to help optimize our cached data. For example, use `2021-07-17T12:00:00Z` and not `2021-07-17T12:23:34Z`._ > ### 🅽🅾🆃🅴 > _The `start_date` can only be a maximum of 30 days in the past._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: 2020-11-27T00:00:00Z X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ 1, 20, 34, 50 ] ## Summary [/movies/{id}] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get a movie [GET] #### ✨ Extended Info Returns a single movie's details. > ### 🅽🅾🆃🅴 > _When getting `full` extended info, the `status` field can have a value of `released`, `in production`, `post production`, `planned`, `rumored`, or `canceled`._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /movies/tron-legacy-2010 ``` + Body { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } + Response 200 (application/json) ``` /movies/tron-legacy-2010?extended=full ``` + Body { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 343, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 }, "tagline": "The Game Has Changed.", "overview": "Sam Flynn, the tech-savvy and daring son of Kevin Flynn, investigates his father's disappearance and is pulled into The Grid. With the help of a mysterious program named Quorra, Sam quests to stop evil dictator Clu from crossing into the real world.", "released": "2010-12-16", "runtime": 125, "country": "us", "updated_at": "2014-07-23T03:21:46.000Z", "trailer": null, "homepage": "http://disney.go.com/tron/", "status": "released", "rating": 8.0, "votes": 111, "comment_count": 92, "languages": ["en"], "available_translations": ["en"], "genres": ["action"], "certification": "PG-13", "original_title": "TRON: Legacy" } ## Aliases [/movies/{id}/aliases] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all movie aliases [GET] Returns all title aliases for a movie. Includes country where name is different. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title": "Batman 1 - Batman Begins", "country": "ca" }, { "title": "Batman 5 Begins", "country": "br" }, { "title": "Batman inicia", "country": "ar" }, { "title": "Batman 5: Batman Begins", "country": "us" }, { "title": "蝙蝠俠：開戰時刻", "country": "tw" }, { "title": "Batman: Na začetku", "country": "si" }, { "title": "Batman Begins", "country": "es" }, { "title": "Batman Begins", "country": "de" }, { "title": "Batman - Batman Begins", "country": "no" }, { "title": "Batman:Le commencement", "country": "ca" }, { "title": "Batman Dark Knight 1: Batman Begins", "country": "us" }, { "title": "蝙蝠侠：侠影之谜", "country": "cn" }, { "title": "Бэтмен: Начало", "country": "ru" }, { "title": "Бетмен: Початок", "country": "ua" }, { "title": "배트맨 비긴즈", "country": "kr" } ] ## Releases [/movies/{id}/releases/{country}] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID + country (optional, string, `us`) ... 2 character country code ### Get all movie releases [GET] Returns all releases for a movie including country, certification, release date, release type, and note. The release type can be set to `unknown`, `premiere`, `limited`, `theatrical`, `digital`, `physical`, or `tv`. The `note` might have optional info such as the film festival name for a `premiere` release or Blu-ray specs for a `physical` release. We pull this info from [TMDB](https://developers.themoviedb.org/3/movies/get-movie-release-dates). + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "country": "us", "certification": "PG", "release_date": "2010-12-16", "release_type": "theatrical", "note": null }, { "country": "gb", "certification": "PG", "release_date": "2010-12-17", "release_type": "theatrical", "note": null }, { "country": "de", "certification": "12", "release_date": "2011-01-26", "release_type": "theatrical", "note": null }, { "country": "fr", "certification": "U", "release_date": "2011-02-09", "release_type": "theatrical", "note": null }, { "country": "it", "certification": "", "release_date": "2010-12-29", "release_type": "theatrical", "note": null }, { "country": "tr", "certification": "PG-13", "release_date": "2011-01-28", "release_type": "theatrical", "note": null }, { "country": "ca", "certification": "", "release_date": "2010-12-17", "release_type": "theatrical", "note": null }, { "country": "nl", "certification": "12", "release_date": "2011-01-28", "release_type": "theatrical", "note": null }, { "country": "kz", "certification": "Б14", "release_date": "2010-12-15", "release_type": "theatrical", "note": null }, { "country": "sk", "certification": "12", "release_date": "2011-01-06", "release_type": "theatrical", "note": null }, { "country": "kr", "certification": "전체 관람가", "release_date": "2010-12-29", "release_type": "theatrical", "note": null }, { "country": "au", "certification": "PG", "release_date": "2010-12-16", "release_type": "theatrical", "note": null }, { "country": "gr", "certification": "PG", "release_date": "2010-12-16", "release_type": "theatrical", "note": null } ] ## Translations [/movies/{id}/translations/{language}] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID + language (optional, string, `es`) ... 2 character language code ### Get all movie translations [GET] 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`). + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title": "Batman Begins", "overview": "Driven by tragedy, billionaire Bruce Wayne dedicates his life to uncovering and defeating the corruption that plagues his home, Gotham City. Unable to work within the system, he instead creates a new identity, a symbol of fear for the criminal underworld - The Batman.", "tagline": "Evil fears the knight.", "language": "en", "country": "us" }, { "title": "Batman Begins", "overview": "...", "tagline": "Das Böse fürchtet den Ritter.", "language": "de", "country": "de" }, { "title": "Batman Begins", "overview": "...", "tagline": "", "language": "da", "country": "da" } ] ## Comments [/movies/{id}/comments/{sort}] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `plays` + `rating` + `added` ### Get all movie comments [GET] #### 🔓 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Great movie!", "spoiler": false, "review": false, "replies": 1, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Lists [/movies/{id}/lists/{type}/{sort}] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID + type (optional, string, `personal`) ... Filter for a specific list type + Values + `all` + `personal` + `official` + `watchlists` + `favorites` + sort (optional, string, `popular`) ... How to sort + Values + `popular` + `likes` + `comments` + `items` + `added` + `updated` ### Get lists containing this movie [GET] #### 📄 Pagination 😁 Emojis Returns all lists that contain this movie. By default, `personal` lists are returned sorted by the most `popular`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "name": "Incredible Thoughts", "description": "How could my brain conceive them?", "privacy": "public", "share_link": "https://trakt.tv/lists/1337", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 10, "likes": 99, "ids": { "trakt": 1337, "slug": "incredible-thoughts" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## People [/movies/{id}/people] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all people for a movie [GET] #### ✨ 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "cast":[ { "characters":[ "Sam Flynn" ], "person":{ "name":"Garrett Hedlund", "ids":{ "trakt":1, "slug":"garrett-hedlund", "imdb":"nm1330560", "tmdb":9828 } } }, { "characters":[ "Kevin Flynn", "Clu" ], "person":{ "name":"Jeff Bridges", "ids":{ "trakt":2, "slug":"jeff-bridges", "imdb":"nm0000313", "tmdb":1229 } } }, { "characters":[ "Quorra" ], "person":{ "name":"Olivia Wilde", "ids":{ "trakt":3, "slug":"olivia-wilde", "imdb":"nm1312575", "tmdb":59315 } } }, { "characters":[ "Alan Bradley", "Tron" ], "person":{ "name":"Bruce Boxleitner", "ids":{ "trakt":4, "slug":"bruce-boxleitner", "imdb":"nm0000310", "tmdb":2547 } } }, { "characters":[ "Siren" ], "person":{ "name":"Yaya DaCosta", "ids":{ "trakt":5, "slug":"yaya-dacosta", "imdb":"", "tmdb":60033 } } }, { "characters":[ "Siren" ], "person":{ "name":"Serinda Swan", "ids":{ "trakt":6, "slug":"serinda-swan", "imdb":"", "tmdb":86268 } } }, { "characters":[ "Siren" ], "person":{ "name":"Beau Garrett", "ids":{ "trakt":7, "slug":"beau-garrett", "imdb":"nm1683768", "tmdb":20403 } } }, { "characters":[ "Siren" ], "person":{ "name":"Elizabeth Mathis", "ids":{ "trakt":8, "slug":"elizabeth-mathis", "imdb":"", "tmdb":130108 } } }, { "characters":[ "Jarvis" ], "person":{ "name":"James Frain", "ids":{ "trakt":9, "slug":"james-frain", "imdb":"nm0289656", "tmdb":22063 } } }, { "characters":[ "Young Mrs. Flynn" ], "person":{ "name":"Amy Esterle", "ids":{ "trakt":10, "slug":"amy-esterle", "imdb":"", "tmdb":86269 } } }, { "characters":[ "Sobel" ], "person":{ "name":"Brandon Jay McLaren", "ids":{ "trakt":11, "slug":"brandon-jay-mclaren", "imdb":"", "tmdb":58371 } } }, { "characters":[ "Castor", "Zuse" ], "person":{ "name":"Michael Sheen", "ids":{ "trakt":12, "slug":"michael-sheen", "imdb":"nm0790688", "tmdb":3968 } } }, { "characters":[ "Young Sam" ], "person":{ "name":"Owen Best", "ids":{ "trakt":13, "slug":"owen-best", "imdb":"", "tmdb":109205 } } }, { "characters":[ "Green Light Cycle Rider" ], "person":{ "name":"Michael Teigen", "ids":{ "trakt":14, "slug":"michael-teigen", "imdb":"nm1083137", "tmdb":37980 } } }, { "characters":[ "Masked DJ's" ], "person":{ "name":"Daft Punk", "ids":{ "trakt":15, "slug":"daft-punk", "imdb":"", "tmdb":67931 } } }, { "characters":[ "Chattering Homeless Man" ], "person":{ "name":"Ron Selmour", "ids":{ "trakt":16, "slug":"ron-selmour", "imdb":"", "tmdb":10874 } } }, { "characters":[ "Bartik" ], "person":{ "name":"Conrad Coates", "ids":{ "trakt":17, "slug":"conrad-coates", "imdb":"", "tmdb":43263 } } }, { "characters":[ "Half Faced Man (as Yurij Kis)" ], "person":{ "name":"Kis Yurij", "ids":{ "trakt":18, "slug":"kis-yurij", "imdb":"", "tmdb":145110 } } } ], "crew":{ "production":[ { "jobs":[ "Casting" ], "person":{ "name":"Heike Brandstatter", "ids":{ "trakt":19, "slug":"heike-brandstatter", "imdb":"nm0104840", "tmdb":5362 } } }, { "jobs":[ "Casting" ], "person":{ "name":"Sarah Finn", "ids":{ "trakt":20, "slug":"sarah-finn", "imdb":"nm0278168", "tmdb":7232 } } }, { "jobs":[ "Casting" ], "person":{ "name":"Coreen Mayrs", "ids":{ "trakt":21, "slug":"coreen-mayrs", "imdb":"nm0563042", "tmdb":5363 } } }, { "jobs":[ "Producer" ], "person":{ "name":"Sean Bailey", "ids":{ "trakt":34, "slug":"sean-bailey", "imdb":"", "tmdb":39387 } } }, { "jobs":[ "Producer" ], "person":{ "name":"Steven Lisberger", "ids":{ "trakt":33, "slug":"steven-lisberger", "imdb":"", "tmdb":12859 } } }, { "jobs":[ "Producer" ], "person":{ "name":"Jeffrey Silver", "ids":{ "trakt":35, "slug":"jeffrey-silver", "imdb":"", "tmdb":20908 } } }, { "jobs":[ "Producer" ], "person":{ "name":"Bruce Franklin", "ids":{ "trakt":36, "slug":"bruce-franklin", "imdb":"", "tmdb":113981 } } }, { "jobs":[ "Producer" ], "person":{ "name":"Steve Gaub", "ids":{ "trakt":37, "slug":"steve-gaub", "imdb":"", "tmdb":63289 } } }, { "jobs":[ "Producer" ], "person":{ "name":"Justis Greene", "ids":{ "trakt":38, "slug":"justis-greene", "imdb":"", "tmdb":113982 } } }, { "jobs":[ "Producer" ], "person":{ "name":"Julien Lemaitre", "ids":{ "trakt":39, "slug":"julien-lemaitre", "imdb":"", "tmdb":113983 } } }, { "job":[ "Executive Producer" ], "person":{ "name":"Donald Kushner", "ids":{ "trakt":40, "slug":"donald-kushner", "imdb":"", "tmdb":6889 } } } ], "art":[ { "jobs":[ "Production Design" ], "person":{ "name":"Darren Gilford", "ids":{ "trakt":22, "slug":"darren-gilford", "imdb":"", "tmdb":411385 } } }, { "jobs":[ "Set Decoration" ], "person":{ "name":"Lin MacDonald", "ids":{ "trakt":25, "slug":"lin-macdonald", "imdb":"nm0003106", "tmdb":12384 } } } ], "crew":[ { "jobs":[ "Supervising Art Director" ], "person":{ "name":"Kevin Ishioka", "ids":{ "trakt":23, "slug":"kevin-ishioka", "imdb":"nm0411131", "tmdb":6878 } } }, { "jobs":[ "Supervising Art Director" ], "person":{ "name":"Mark W. Mansbridge", "ids":{ "trakt":24, "slug":"mark-w-mansbridge", "imdb":"nm0543729", "tmdb":21070 } } } ], "costume & make-up":[ { "jobs":[ "Costume Design" ], "person":{ "name":"Michael Wilkinson", "ids":{ "trakt":26, "slug":"michael-wilkinson", "imdb":"nm0929452", "tmdb":5392 } } }, { "jobs":[ "Makeup Department Head" ], "person":{ "name":"Rosalina Da Silva", "ids":{ "trakt":27, "slug":"rosalina-da-silva", "imdb":"nm0196301", "tmdb":75294 } } }, { "jobs":[ "Costume Supervisor" ], "person":{ "name":"Tangi Crawford", "ids":{ "trakt":28, "slug":"tangi-crawford", "imdb":"", "tmdb":1323289 } } } ], "directing":[ { "jobs":[ "Director" ], "person":{ "name":"Joseph Kosinski", "ids":{ "trakt":29, "slug":"joseph-kosinski", "imdb":"nm2676052", "tmdb":86270 } } } ], "writing":[ { "jobs":[ "Screenplay" ], "person":{ "name":"Adam Horowitz", "ids":{ "trakt":30, "slug":"adam-horowitz", "imdb":"", "tmdb":44035 } } }, { "job":[ "Screenplay" ], "person":{ "name":"Richard Jefferies", "ids":{ "trakt":31, "slug":"richard-jefferies", "imdb":"", "tmdb":73570 } } }, { "jobs":[ "Screenplay" ], "person":{ "name":"Edward Kitsis", "ids":{ "trakt":32, "slug":"edward-kitsis", "imdb":"", "tmdb":44034 } } }, { "jobs":[ "Screenplay" ], "person":{ "name":"Steven Lisberger", "ids":{ "trakt":33, "slug":"steven-lisberger", "imdb":"", "tmdb":12859 } } } ], "sound":[ { "jobs":[ "Music" ], "person":{ "name":"Daft Punk", "ids":{ "trakt":15, "slug":"daft-punk", "imdb":"", "tmdb":67931 } } } ], "camera":[ { "jobs":[ "Director of Photography" ], "person":{ "name":"Claudio Miranda", "ids":{ "trakt":41, "slug":"claudio-miranda", "imdb":"", "tmdb":51333 } } } ] } } ## Ratings [/movies/{id}/ratings] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get movie ratings [GET] Returns rating (between 0 and 10) and distribution for a movie. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "rating": 7.33778, "votes": 7866, "distribution": { "1": 298, "2": 46, "3": 87, "4": 178, "5": 446, "6": 1167, "7": 1855, "8": 1543, "9": 662, "10": 1583 } } ## Related [/movies/{id}/related] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get related movies [GET] #### 📄 Pagination ✨ Extended Info Returns related and similar movies. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "title": "Jurassic Park", "year": 1993, "ids": { "trakt": 393, "slug": "jurassic-park-1993", "imdb": "tt0107290", "tmdb": 329 } }, { "title": "Back to the Future", "year": 1985, "ids": { "trakt": 308, "slug": "back-to-the-future-1985", "imdb": "tt0088763", "tmdb": 105 } }, { "title": "Kick-Ass", "year": 2010, "ids": { "trakt": 171, "slug": "kick-ass-2010", "imdb": "tt1250777", "tmdb": 23483 } }, { "title": "The Hangover", "year": 2009, "ids": { "trakt": 547, "slug": "the-hangover-2009", "imdb": "tt1119646", "tmdb": 18785 } }, { "title": "Back to the Future Part II", "year": 1989, "ids": { "trakt": 384, "slug": "back-to-the-future-part-ii-1989", "imdb": "tt0096874", "tmdb": 165 } }, { "title": "Zombieland", "year": 2009, "ids": { "trakt": 205, "slug": "zombieland-2009", "imdb": "tt1156398", "tmdb": 19908 } }, { "title": "Inception", "year": 2010, "ids": { "trakt": 108, "slug": "inception-2010", "imdb": "tt1375666", "tmdb": 27205 } }, { "title": "Gladiator", "year": 2000, "ids": { "trakt": 463, "slug": "gladiator-2000", "imdb": "tt0172495", "tmdb": 98 } }, { "title": "Snatch", "year": 2000, "ids": { "trakt": 1473, "slug": "snatch-2000", "imdb": "tt0208092", "tmdb": 107 } }, { "title": "Donnie Darko", "year": 2001, "ids": { "trakt": 114, "slug": "donnie-darko-2001", "imdb": "tt0246578", "tmdb": 141 } } ] ## Stats [/movies/{id}/stats] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get movie stats [GET] Returns lots of movie stats. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "watchers": 39204, "plays": 51033, "collectors": 27379, "comments": 36, "lists": 4561, "votes": 7866, "favorited": 54321 } ## Studios [/movies/{id}/studios] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get movie studios [GET] Returns all studios for a movie. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "name":"20th Century Fox", "country":"us", "ids":{ "trakt":20, "slug":"20th-century-fox", "tmdb":25 } }, { "name":"Marvel Entertainment", "country":"us", "ids":{ "trakt":19, "slug":"marvel-entertainment", "tmdb":7505 } }, { "name":"The Donners' Company", "country":"us", "ids":{ "trakt":25, "slug":"the-donners-company", "tmdb":431 } }, { "name":"TSG Entertainment", "country":"us", "ids":{ "trakt":22, "slug":"tsg-entertainment", "tmdb":22213 } }, { "name":"Genre Films", "country":"us", "ids":{ "trakt":23, "slug":"genre-films", "tmdb":28788 } } ] ## Watching [/movies/{id}/watching] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get users watching right now [GET] #### ✨ Extended Info Returns all users watching this movie right now. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } }, { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } ] ## Videos [/movies/{id}/videos] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all videos [GET] #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title":"Official Trailer # 3", "url":"https://youtube.com/watch?v=d4RiUy23e9s", "site":"youtube", "type":"trailer", "size":1080, "official":true, "published_at":"2010-11-09T01:07:39.000Z", "country":"us", "language":"en" } ] ## Refresh [/movies/{id}/refresh] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Refresh movie metadata [POST] #### 🔥 VIP Only 🔒 OAuth Required Queue this movie for a full metadata and image refresh. It might take up to 8 hours for the updated metadata to be availabe through the API. > ### 🅽🅾🆃🅴 > _If this movie is already queued, a `409` HTTP status code will returned._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 201 (application/json) ## Report [/movies/{id}/report] + Parameters + id (required, string, `tron-legacy-2010`) ... Trakt ID, Trakt slug, or IMDB ID ### Report a movie [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "metadata", "message": "Runtime should be 125 minutes." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: duplicate, remove, data_refresh, metadata, adult, runtime, language, spam, tmdb, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } # Group Networks ## List [/networks] #### 📄 Pagination Optional Most TV shows have a TV network where it originally aired. Some API methods allow filtering by network, so it's good to cache this list in your app. ### Get networks [GET] Get a list of all TV networks, including the `name`, `country`, and `ids`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "name": "A&E", "country": "us", "ids": { "trakt": 44, "tmdb": 129 } }, { "name": "ABC", "country": "us", "ids": { "trakt": 16, "tmdb": 2 } }, { "name": "AMC", "country": "us", "ids": { "trakt": 107, "tmdb": 174 } } ] # Group Notes Notes *(500 maximum characters)* attached to any `movie`, `show`, `season`, `episode`, or `person` and are only visible to the user who created them. They are also set to `private` and can't be marked as a `spoiler`. Notes attached to any `history`, `collection`, or `rating` can have their `privacy` and `spoiler` set. #### Possible Error Responses | Code | Description | |---|---| | `401` | Invalid user | `404` | Item not found or doesn't allow notes | `409` | Note can't be deleted | `422` | Validation errors ## Notes [/notes] ### Add notes [POST] #### 🔥 VIP Enhanced 🔒 OAuth Required 😁 Emojis Notes *(500 maximum characters)* added to a `movie`, `show`, `season`, `episode`, or `person` will automatically be set to `private`. You can send just the media item. Notes *(500 maximum characters)* added to a `history`, `collection`, or `rating` can have their `privacy` and `spoiler` set. You need to send the `attached_to` object so we know where to attach the note. #### Limits If the user's note 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. Upgrading to [**Trakt VIP**](https://trakt.tv/vip) allows for unlimited notes. #### JSON POST Data | Key | Type | Default | Value | |---|---|---|---| | item * | object | | `movie`, `show`, `season`, `episode`, `person`, 'history', 'collection', 'rating' object. (see examples →) | | `notes` * | string | | Text for the notes. | | `spoiler` | boolean | `false` | Is this a spoiler? | | `privacy` | string | `private` | `private`, `friends`, `public` | + Request (application/json) Movie note by sending a `movie` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } }, "notes": "Watch this in IMAX!" } + Response 201 (application/json) + Body { "id": 190, "notes": "Watch this in IMAX!", "privacy":"private", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) Show note by sending a `show` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "Breaking Bad", "ids": { "trakt": 1, "slug": "breaking-bad" } }, "notes": "Welcome to Pollos Hermanos!" } + Response 201 (application/json) + Body { "id": 191, "notes": "Welcome to Pollos Hermanos!", "privacy":"private", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) Season note by sending a `season` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "season": { "ids": { "trakt": 16 } }, "notes": "Hello Gus." } + Response 201 (application/json) + Body { "id": 192, "notes": "Hello Gus.", "privacy":"private", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) Episode note by sending a `episode` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "episode": { "ids": { "trakt": 16 } }, "notes": "I am the danger!" } + Response 201 (application/json) + Body { "id": 193, "notes": "I am the danger!", "privacy":"private", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) Person note by sending a `person` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "person": { "ids": { "trakt": 16 } }, "notes": "Every movie they direct is a masterpiece." } + Response 201 (application/json) + Body { "id": 194, "notes": "Every movie they direct is a masterpiece.", "privacy":"private", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) `history` note for a specifc play of a `movie`. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "attached_to": { "type": "history", "id": 43453489 }, "privacy": "public", "notes": "Saw this in Dolby Cinema!" } + Response 201 (application/json) + Body { "id": 190, "notes": "Saw this in Dolby Cinema!", "privacy":"public", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) `collection` note for a collected `movie`. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "attached_to": { "type": "collection" }, "privacy": "public", "movie": { "title": "The Goonies", "year": 1985, "ids": { "trakt": 4633, "slug": "the-goonies-1985", "imdb": "tt0089218", "tmdb": 9340 } }, "notes": "Owned on 4K Blu-ray, DVD, VHS, and LaserDisc." } + Response 201 (application/json) + Body { "id": 190, "notes": "Owned on 4K Blu-ray, DVD, VHS, and LaserDisc.", "privacy":"public", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } + Request (application/json) `rating` note for a rated `movie`. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "attached_to": { "type": "rating" }, "privacy": "public", "movie": { "title": "The Goonies", "year": 1985, "ids": { "trakt": 4633, "slug": "the-goonies-1985", "imdb": "tt0089218", "tmdb": 9340 } }, "notes": "Cinemetography: 10/10\nActing: 10/10\nSoundtrack: 10/10\n\nOverall: 10/10" } + Response 201 (application/json) + Body { "id": 190, "notes": "Cinemetography: 10/10\nActing: 10/10\nSoundtrack: 10/10\n\nOverall: 10/10", "privacy":"public", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ## Note [/notes/{id}] + Parameters + id (required, integer, `193`) ... A specific note ID. ### Get a note [GET] #### 🔒 OAuth Required 😁 Emojis Returns a single note. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Item-ID: 1337 X-Item-Type: show + Body { "id": 193, "notes": "I am the danger!", "privacy":"private", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-12T20:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ### Update a note [PUT] #### 🔒 OAuth Required 😁 Emojis Update a single note *(500 maximum characters)*. The OAuth user must match the author of the note in order to update it. If not, a `401` HTTP status is returned. #### JSON POST Data | Key | Type | Default | Value | |---|---|---|---| | `notes` | string | | Text for the notes. | | `spoiler` | boolean | `false` | Is this a spoiler? | | `privacy` | string | `private` | `private`, `friends`, `public` | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "notes": "I AM THE DANGER! I AM THE ONE WHO KNOCKS!" } + Response 200 (application/json) + Body { "id": 193, "notes": "I AM THE DANGER! I AM THE ONE WHO KNOCKS!", "privacy":"private", "spoiler":false, "created_at":"2023-09-12T20:10:18.000Z", "updated_at":"2023-09-13T06:10:56.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ### Delete a note [DELETE] #### 🔒 OAuth Required Delete a single note. The OAuth user must match the author of the comment in order to delete it. If not, a `401` HTTP status code is returned. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 ## Item [/notes/{id}/item] + Parameters + id (required, integer, `417`) ... A specific note ID. ### Get the attached item [GET] #### ✨ Extended Info Returns the item this note is `attached_to`. Media items like `movie`, `show`, `season`, `episode`, or `person` are straightforward, but `history` will need to be mapped to that specific play in their watched history since they might have multiple plays. Since `collection` and `rating` is a 1:1 association, you can assume the note is attached to the media item in the `type` field that has been collected or rated. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) Attached to a standard media item. + Body { "attached_to": { "type": "show" }, "type": "show", "show": { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 353, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } } } + Response 200 (application/json) Attached to a specific watched history item. + Body { "attached_to": { "type": "history", "id": 4943432 }, "type": "show", "show": { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 353, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } } } # Group People ## Updates [/people/updates/{start_date}] + Parameters + start_date (optional, string, `2020-11-27T00:00:00Z`) ... Updated since this date and time. ### Get recently updated people [GET] #### 📄 Pagination ✨ Extended Info Returns all people updated since the specified UTC date and time. We recommended storing the `X-Start-Date` header you can be efficient using this method moving forward. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _The `start_date` is only accurate to the hour, for caching purposes. Please drop the minutes and seconds from your timestamp to help optimize our cached data. For example, use `2021-07-17T12:00:00Z` and not `2021-07-17T12:23:34Z`._ > ### 🅽🅾🆃🅴 > _The `start_date` can only be a maximum of 30 days in the past._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: 2020-11-27T00:00:00Z X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "updated_at": "2022-11-03T18:58:09.000Z", "person": { "name": "Charlie Cox", "ids": { "trakt": 417084, "slug": "charlie-cox", "imdb": "nm1214435", "tmdb": 23458 } } }, { "updated_at": "2022-11-03T18:58:09.000Z", "person": { "name": "Deborah Ann Woll", "ids": { "trakt": 451773, "slug": "deborah-ann-woll", "imdb": "nm2832695", "tmdb": 212154 } } } ] ## Updated IDs [/people/updates/id/{start_date}] + Parameters + start_date (optional, string, `2020-11-27T00:00:00Z`) ... Updated since this date and time. ### Get recently updated people Trakt IDs [GET] #### 📄 Pagination Returns all people Trakt IDs updated since the specified UTC date and time. We recommended storing the `X-Start-Date` header you can be efficient using this method moving forward. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _The `start_date` is only accurate to the hour, for caching purposes. Please drop the minutes and seconds from your timestamp to help optimize our cached data. For example, use `2021-07-17T12:00:00Z` and not `2021-07-17T12:23:34Z`._ > ### 🅽🅾🆃🅴 > _The `start_date` can only be a maximum of 30 days in the past._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: 2020-11-27T00:00:00Z X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ 1, 20, 34, 50 ] ## Summary [/people/{id}] + Parameters + id (required, string, `bryan-cranston`) ... Trakt ID, Trakt slug, or IMDB ID ### Get a single person [GET] #### ✨ 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /people/bryan-cranston ``` + Body { "name": "Bryan Cranston", "ids": { "trakt": 142, "slug": "bryan-cranston", "imdb": "nm0186505", "tmdb": 17419 } } + Response 200 (application/json) ``` /people/bryan-cranston?extended=full ``` + Body { "name": "Bryan Cranston", "ids": { "trakt": 1, "slug": "bryan-cranston", "imdb": "nm0186505", "tmdb": 17419 }, "social_ids": { "twitter": "BryanCranston", "facebook": "thebryancranston", "instagram": "bryancranston", "wikipedia": null }, "biography": "Bryan Lee Cranston (born March 7, 1956) is an American actor, voice actor, writer and director.He is perhaps best known for his roles as Hal, the father in the Fox situation comedy \"Malcolm in the Middle\", and as Walter White in the AMC drama series Breaking Bad, for which he has won three consecutive Outstanding Lead Actor in a Drama Series Emmy Awards. Other notable roles include Dr. Tim Whatley on Seinfeld, Doug Heffernan's neighbor in The King of Queens, Astronaut Buzz Aldrin in From the Earth to the Moon, and Ted Mosby's boss on How I Met Your Mother. Description above from the Wikipedia article Bryan Cranston, licensed under CC-BY-SA, full list of contributors on Wikipedia.", "birthday": "1956-03-07", "death": null, "birthplace": "San Fernando Valley, California, USA", "homepage": "http://www.bryancranston.com/", "gender": "male", "known_for_department": "acting", "updated_at": "2022-11-03T17:00:54.000Z" } ## Movies [/people/{id}/movies] + Parameters + id (required, string, `bryan-cranston`) ... Trakt ID, Trakt slug, or IMDB ID ### Get movie credits [GET] #### ✨ 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "cast": [ { "characters": ["Joe Brody"], "movie": { "title": "Godzilla", "year": 2014, "ids": { "trakt": 24, "slug": "godzilla-2014", "imdb": "tt0831387", "tmdb": 124905 } } } ], "crew": { "directing": [ { "jobs": ["Director"], "movie": { "title": "Godzilla", "year": 2014, "ids": { "trakt": 24, "slug": "godzilla-2014", "imdb": "tt0831387", "tmdb": 124905 } } } ], "writing": [ { "jobs": ["Screenplay"], "movie": { "title": "Godzilla", "year": 2014, "ids": { "trakt": 24, "slug": "godzilla-2014", "imdb": "tt0831387", "tmdb": 124905 } } } ], "producing": [ { "jobs": ["Producer"], "movie": { "title": "Godzilla", "year": 2014, "ids": { "trakt": 24, "slug": "godzilla-2014", "imdb": "tt0831387", "tmdb": 124905 } } } ] } } ## Shows [/people/{id}/shows] + Parameters + id (required, string, `bryan-cranston`) ... Trakt ID, Trakt slug, or IMDB ID ### Get show credits [GET] #### ✨ 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "cast": [ { "characters": ["Walter White"], "episode_count": 62, "series_regular": true, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ], "crew": { "production": [ { "jobs": ["Producer"], "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] } } ## Lists [/people/{id}/lists/{type}/{sort}] + Parameters + id (required, string, `bryan-cranston`) ... Trakt ID, Trakt slug, or IMDB ID + type (optional, string, `personal`) ... Filter for a specific list type + Values + `all` + `personal` + `official` + sort (optional, string, `popular`) ... How to sort + Values + `popular` + `likes` + `comments` + `items` + `added` + `updated` ### Get lists containing this person [GET] #### 📄 Pagination 😁 Emojis Returns all lists that contain this person. By default, `personal` lists are returned sorted by the most `popular`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "name": "Incredible Thoughts", "description": "How could my brain conceive them?", "privacy": "public", "share_link": "https://trakt.tv/lists/1337", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 10, "likes": 99, "ids": { "trakt": 1337, "slug": "incredible-thoughts" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## Refresh [/people/{id}/refresh] + Parameters + id (required, string, `bryan-cranston`) ... Trakt ID, Trakt slug, or IMDB ID ### Refresh person metadata [POST] #### 🔥 VIP Only 🔒 OAuth Required Queue this person for a full metadata and image refresh. It might take up to 8 hours for the updated metadata to be availabe through the API. > ### 🅽🅾🆃🅴 > _If this person is already queued, a `409` HTTP status code will returned._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 201 (application/json) ## Report [/people/{id}/report] + Parameters + id (required, string, `bryan-cranston`) ... Trakt ID, Trakt slug, or IMDB ID ### Report a person [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "metadata", "message": "Wrong birthdate listed." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: duplicate, remove, data_refresh, metadata, adult, language, spam, tmdb, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } # Group Recommendations Trakt recommendations are built on top of your viewing activity and preferences. The more you watch, the better your recommendations will be. We also use other factors for the algorithm to further personalize what gets recommended. ## Movies [/recommendations/movies{?ignore_collected,ignore_watchlisted}] + Parameters + ignore_collected (optional, string, `false`) ... filter out collected movies + Values + `true` + `false` + ignore_watchlisted (optional, string, `false`) ... filter out watchlisted movies + Values + `true` + `false` ### Get movie recommendations [GET] #### 🔒 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 + Body [ { "title": "Blackfish", "year": 2013, "ids": { "trakt": 58, "slug": "blackfish-2013", "imdb": "tt2545118", "tmdb": 158999 }, "favorited_by": [ { "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } }, "notes": "This is a great documentary about killer whales." } ] }, { "title": "Waiting for Superman", "year": 2010, "ids": { "trakt": 289, "slug": "waiting-for-superman-2010", "imdb": "tt1566648", "tmdb": 39440 }, "favorited_by": [ ] }, { "title": "Inside Job", "year": 2010, "ids": { "trakt": 329, "slug": "inside-job-2010", "imdb": "tt1645089", "tmdb": 44639 }, "favorited_by": [ ] }, { "title": "School of Rock", "year": 2003, "ids": { "trakt": 503, "slug": "school-of-rock-2003", "imdb": "tt0332379", "tmdb": 1584 }, "favorited_by": [ ] }, { "title": "The Lincoln Lawyer", "year": 2011, "ids": { "trakt": 513, "slug": "the-lincoln-lawyer-2011", "imdb": "tt1189340", "tmdb": 50348 }, "favorited_by": [ ] }, { "title": "The Change-Up", "year": 2011, "ids": { "trakt": 822, "slug": "the-change-up-2011", "imdb": "tt1488555", "tmdb": 49520 }, "favorited_by": [ ] }, { "title": "50/50", "year": 2011, "ids": { "trakt": 907, "slug": "50-50-2011", "imdb": "tt1306980", "tmdb": 40807 }, "favorited_by": [ ] }, { "title": "Moneyball", "year": 2011, "ids": { "trakt": 945, "slug": "moneyball-2011", "imdb": "tt1210166", "tmdb": 60308 }, "favorited_by": [ ] }, { "title": "Killer at Large", "year": 2008, "ids": { "trakt": 3549, "slug": "killer-at-large-2008", "imdb": "tt0903660", "tmdb": 37312 }, "favorited_by": [ ] }, { "title": "Green Day: Bullet in a Bible", "year": 2005, "ids": { "trakt": 3770, "slug": "green-day-bullet-in-a-bible-2005", "imdb": "tt0485773", "tmdb": 26627 }, "favorited_by": [ ] } ] ## Hide Movie [/recommendations/movies/{id}] + Parameters + id (required, string, `922`) ... Trakt ID, Trakt slug, or IMDB ID ### Hide a movie recommendation [DELETE] #### 🔒 OAuth Required Hide a movie from getting recommended anymore. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 ## Shows [/recommendations/shows{?ignore_collected,ignore_watchlisted}] + Parameters + ignore_collected (optional, string, `false`) ... filter out collected shows + Values + `true` + `false` + ignore_watchlisted (optional, string, `false`) ... filter out watchlisted movies + Values + `true` + `false` ### Get show recommendations [GET] #### 🔒 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 + Body [ { "title": "The Biggest Loser", "year": 2004, "ids": { "trakt": 9, "slug": "the-biggest-loser", "tvdb": 75166, "imdb": "tt0429318", "tmdb": 579 }, "favorited_by": [ { "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } }, "notes": "This show is inspiring!" } ] }, { "title": "Shark Tank", "year": 2009, "ids": { "trakt": 36, "slug": "shark-tank", "tvdb": 100981, "imdb": "tt1442550", "tmdb": 30703 }, "favorited_by": [ ] }, { "title": "Hell's Kitchen", "year": 2005, "ids": { "trakt": 40, "slug": "hell-s-kitchen", "tvdb": 74897, "imdb": "tt0437005", "tmdb": 2370 }, "favorited_by": [ ] }, { "title": "The Big C", "year": 2010, "ids": { "trakt": 51, "slug": "the-big-c", "tvdb": 161501, "imdb": "tt1515193", "tmdb": 32406 }, "favorited_by": [ ] }, { "title": "United States of Tara", "year": 2009, "ids": { "trakt": 69, "slug": "united-states-of-tara", "tvdb": 83463, "imdb": "tt1001482", "tmdb": 7097 }, "favorited_by": [ ] }, { "title": "Hung", "year": 2009, "ids": { "trakt": 168, "slug": "hung", "tvdb": 82091, "imdb": "tt1229413", "tmdb": 18614 }, "favorited_by": [ ] }, { "title": "Big Love", "year": 2006, "ids": { "trakt": 272, "slug": "big-love", "tvdb": 74156, "imdb": "tt0421030", "tmdb": 4392 }, "favorited_by": [ ] }, { "title": "Brooklyn Nine-Nine", "year": 2013, "ids": { "trakt": 599, "slug": "brooklyn-nine-nine", "tvdb": 269586, "imdb": "tt2467372", "tmdb": 48891 }, "favorited_by": [ ] }, { "title": "FlashForward", "year": 2009, "ids": { "trakt": 677, "slug": "flashforward", "tvdb": 84024, "imdb": "tt1441135", "tmdb": 19092 }, "favorited_by": [ ] }, { "title": "Roswell", "year": 1999, "ids": { "trakt": 717, "slug": "roswell", "tvdb": 73965, "imdb": "tt0201391", "tmdb": 4624 }, "favorited_by": [ ] } ] ## Hide Show [/recommendations/shows/{id}] + Parameters + id (required, string, `922`) ... Trakt ID, Trakt slug, or IMDB ID ### Hide a show recommendation [DELETE] #### 🔒 OAuth Required Hide a show from getting recommended anymore. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 # Group Scrobble Scrobbling is an automatic way to track what a user is watching in a media center. The media center should send events that correspond to starting, pausing, and stopping (or finishing) watching a movie or episode. ## Start [/scrobble/start] ### Start watching in a media center [POST] #### 🔒 OAuth Required Use this method when the video initially starts playing or is unpaused. This will remove any playback progress if it exists. > ### 🅽🅾🆃🅴 > _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. | + Request (application/json) Start watching a movie by sending a standard `movie` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } }, "progress": 1.25 } + Response 201 (application/json) + Body { "id": 0, "action": "start", "progress": 1.25, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } } + Request (application/json) Start watching an episode by sending a standard `episode` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "episode": { "ids": { "trakt": 16 } }, "progress": 10.0 } + Response 201 (application/json) + Body { "id": 0, "action": "start", "progress": 10.0, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 16, "tvdb": 349232, "imdb": "tt0959621", "tmdb": 62085 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } + Request (application/json) Start watching an episode if you don't have episode ids, but have show info. Send `show` and `episode` objects. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "tvdb": 81189 } }, "episode": { "season": 1, "number": 1 }, "progress": 10.0 } + Response 201 (application/json) + Body { "id": 0, "action": "start", "progress": 10.0, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 16, "tvdb": 349232, "imdb": "tt0959621", "tmdb": 62085 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } + Request (application/json) Start watching an episode using absolute numbering (useful for Anime and Donghua). Send `show` and `episode` objects. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "One Piece", "year": 1999, "ids": { "trakt": 37696 } }, "episode": { "number_abs": 164 }, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "progress": 10.0 } + Response 201 (application/json) + Body { "id": 0, "action": "start", "progress": 10.0, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 9, "number": 21, "title": "Light the Fire of Shandia! Wiper the Warrior", "ids": { "trakt": 856373, "tvdb": 362082, "imdb": null, "tmdb": null } }, "show": { "title": "One Piece", "year": 1999, "ids": { "trakt": 37696, "slug": "one-piece", "tvdb": 81797, "imdb": "tt0388629", "tmdb": 37854 } } } ## Stop [/scrobble/stop] ### Stop or finish watching in a media center [POST] #### 🔒 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. > ### 🅽🅾🆃🅴 > _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. | > ### 🅽🅾🆃🅴 > _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._ + Request (application/json) Scrobble a movie by sending a standard `movie` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } }, "progress": 99.9 } + Response 201 (application/json) + Body { "id": 3373536622, "action": "scrobble", "progress": 99.9, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } } + Request (application/json) Scrobble an episode by sending a standard `episode` object. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "episode": { "ids": { "trakt": 16 } }, "progress": 85.0 } + Response 201 (application/json) + Body { "id": 3373536623, "action": "scrobble", "progress": 85.0, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 16, "tvdb": 349232, "imdb": "tt0959621", "tmdb": 62085 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } + Request (application/json) Scrobble an episode if you don't have episode ids, but have show info. Send `show` and `episode` objects. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "tvdb": 81189 } }, "episode": { "season": 1, "number": 1 }, "progress": 85.0 } + Response 201 (application/json) + Body { "id": 3373536623, "action": "scrobble", "progress": 85.0, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 1, "number": 1, "title": "Pilot", "ids": { "trakt": 16, "tvdb": 349232, "imdb": "tt0959621", "tmdb": 62085 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } + Request (application/json) Scrobble an episode using absolute numbering (useful for Anime and Donghua). Send `show` and `episode` objects. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "show": { "title": "One Piece", "year": 1999, "ids": { "trakt": 37696 } }, "episode": { "number_abs": 164 }, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "progress": 90.0 } + Response 201 (application/json) + Body { "id": 3373536624, "action": "scrobble", "progress": 90.0, "sharing": { "twitter": true, "mastodon": true, "tumblr": false }, "episode": { "season": 9, "number": 21, "title": "Light the Fire of Shandia! Wiper the Warrior", "ids": { "trakt": 856373, "tvdb": 362082, "imdb": null, "tmdb": null } }, "show": { "title": "One Piece", "year": 1999, "ids": { "trakt": 37696, "slug": "one-piece", "tvdb": 81797, "imdb": "tt0388629", "tmdb": 37854 } } } + Request (application/json) If the progress is < 80%, the video will be treated a a *pause* and the playback position will be saved. + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } }, "progress": 75.0 } + Response 201 (application/json) + Body { "id": 1337, "action": "pause", "progress": 75.0, "sharing": { "twitter": false, "mastodon": true, "tumblr": false }, "movie": { "title": "Guardians of the Galaxy", "year": 2014, "ids": { "trakt": 28, "slug": "guardians-of-the-galaxy-2014", "imdb": "tt2015381", "tmdb": 118340 } } } + Response 409 (application/json) The same item was recently scrobbled. + Body { "watched_at": "2014-10-15T22:21:29.000Z", "expires_at": "2014-10-15T23:21:29.000Z" } # Group Search Searches can use queries or ID lookups. Queries will search text fields like the title and overview. ID lookups are helpful if you have an external ID and want to get the Trakt ID and info. These methods can search for movies, shows, episodes, people, and lists. ## Text Query [/search/{type}{?query}] + Parameters + type (required, string, `movie`) ... Search type. + Values + `movie` + `show` + `episode` + `person` + `list` + query (required, string, `tron`) ... Search all text based fields. + fields (optional, string, `title`) ... Specific text fields. + Values + `title` + `tagline` + `overview` + `people` + `translations` + `aliases` + `name` + `biography` + `description` ### Get text query results [GET] #### 📄 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` | ✓ | + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /search/movie,show,episode,person,list?query=tron ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "type": "movie", "score": 26.019499, "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 12601, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "type": "show", "score": 19.533358, "show": { "title": "Tron: Uprising", "year": 2012, "ids": { "trakt": 34209, "slug": "tron-uprising", "tvdb": 258480, "imdb": "tt1812523", "tmdb": 34356 } } }, { "type": "episode", "score": 42.50835, "episode": { "season": 1, "number": 1, "title": "The Renegade (1)", "ids": { "trakt": 793693, "tvdb": 4318713, "imdb": null, "tmdb": 786460 } }, "show": { "title": "Tron: Uprising", "year": 2012, "ids": { "trakt": 34209, "slug": "tron-uprising", "tvdb": 258480, "imdb": "tt1812523", "tmdb": 34356 } } }, { "type": "person", "score": 53.421608, "person": { "name": "Jeff Bridges", "ids": { "trakt": 4173, "slug": "jeff-bridges", "imdb": "nm0000313", "tmdb": 1229 } } }, { "type": "list", "score": 38.643196, "list": { "name": "Open Your Eyes", "description": "Let food be thy medicine and medicine be thy food.", "privacy": "public", "share_link": "https://trakt.tv/lists/2180135", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2016-04-22T05:54:55.000Z", "updated_at": "2016-06-29T09:47:40.000Z", "item_count": 22, "comment_count": 0, "likes": 6, "ids": { "trakt": 2180135, "slug": "open-your-eyes" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": true, "ids": { "slug": "justin" } } } } ] ## ID Lookup [/search/{id_type}/{id}{?type}] + Parameters + id_type (required, string, `imdb`) ... Type of ID to lookup. + Values + `trakt` + `imdb` + `tmdb` + `tvdb` + id (required, string, `tt0848228`) ... ID that matches with the type. + type (optional, string, `movie`) ... Search type. + Values + `movie` + `show` + `episode` + `person` + `list` ### Get ID lookup results [GET] #### 📄 Pagination ✨ Extended Info Lookup items by their Trakt, IMDB, TMDB, or TVDB ID. If you use the search url without a `type` it might return multiple items if the `id_type` is not globally unique. Specify the `type` of results by sending a single value or a comma delimited string for multiple types. | Type | URL | |---|---| | `trakt` | `/search/trakt/:id` | | | `/search/trakt/:id?type=movie` | | | `/search/trakt/:id?type=show` | | | `/search/trakt/:id?type=episode` | | | `/search/trakt/:id?type=person` | | `imdb` | `/search/imdb/:id` | | `tmdb` | `/search/tmdb/:id` | | | `/search/tmdb/:id?type=movie` | | | `/search/tmdb/:id?type=show` | | | `/search/tmdb/:id?type=episode` | | | `/search/tmdb/:id?type=person` | | `tvdb` | `/search/tvdb/:id` | | | `/search/tvdb/:id?type=show` | | | `/search/tvdb/:id?type=episode` | + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /search/trakt/12601?type=movie /search/imdb/tt1104001 ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 1 + Body [ { "type": "movie", "score": null, "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 12601, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } } ] # Group Shows ## Trending [/shows/trending] ### Get trending shows [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most watched shows over the last 24 hours. Shows with the most `watchers` are returned first. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 X-Trending-User-Count: 1721 + Body [ { "watchers": 541, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "watchers": 432, "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## Popular [/shows/popular] ### Get popular shows [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most popular shows. Popularity is calculated using the rating percentage and the number of ratings. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 + Body [ { "title": "Community", "year": 2009, "ids": { "trakt": 41, "slug": "community", "tvdb": 94571, "imdb": "tt1439629", "tmdb": 18347 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } }, { "title": "Dexter", "year": 2006, "ids": { "trakt": 19, "slug": "dexter", "tvdb": 79349, "imdb": "tt0773262", "tmdb": 1405 } }, { "title": "The Simpsons", "year": 1989, "ids": { "trakt": 91, "slug": "the-simpsons", "tvdb": 71663, "imdb": "tt0096697", "tmdb": 456 } }, { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 353, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } }, { "title": "Lost", "year": 2004, "ids": { "trakt": 511, "slug": "lost", "tvdb": 73739, "imdb": "tt0411008", "tmdb": 4607 } }, { "title": "24", "year": 2001, "ids": { "trakt": 460, "slug": "24", "tvdb": 76290, "imdb": "tt0285331", "tmdb": 1973 } }, { "title": "Battlestar Galactica", "year": 2005, "ids": { "trakt": 331, "slug": "battlestar-galactica", "tvdb": 73545, "imdb": "tt0407362", "tmdb": 1972 } }, { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "Firefly", "year": 2002, "ids": { "trakt": 329, "slug": "firefly", "tvdb": 78874, "imdb": "tt0303461", "tmdb": 1437 } } ] ## Favorited [/shows/favorited/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most favorited shows [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most favorited shows in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "user_count": 155291, "show": { "title": "The Big Bang Theory", "year": 2007, "ids": { "trakt": 1409, "slug": "the-big-bang-theory", "tvdb": 80379, "imdb": "tt0898266", "tmdb": 1418 } } }, { "user_count": 46170, "show": { "title": "Grey's Anatomy", "year": 2005, "ids": { "trakt": 1407, "slug": "grey-s-anatomy", "tvdb": 73762, "imdb": "tt0413573", "tmdb": 1416 } } }, { "user_count": 203742, "show": { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 1390, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } } } ] ## Played [/shows/played/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most played shows [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most played (a single user can watch multiple episodes multiple times) shows in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "watcher_count": 155291, "play_count": 23542030, "collected_count": 6635583, "collector_count": 54953, "show": { "title": "The Big Bang Theory", "year": 2007, "ids": { "trakt": 1409, "slug": "the-big-bang-theory", "tvdb": 80379, "imdb": "tt0898266", "tmdb": 1418 } } }, { "watcher_count": 100242, "play_count": 19787304, "collected_count": 4529880, "collector_count": 32335, "show": { "title": "How I Met Your Mother", "year": 2005, "ids": { "trakt": 1095, "slug": "how-i-met-your-mother", "tvdb": 75760, "imdb": "tt0460649", "tmdb": 1100 } } }, { "watcher_count": 56216, "play_count": 19286818, "collected_count": 7427018, "collector_count": 23876, "show": { "title": "The Simpsons", "year": 1989, "ids": { "trakt": 455, "slug": "the-simpsons", "tvdb": 71663, "imdb": "tt0096697", "tmdb": 456 } } }, { "watcher_count": 8050, "play_count": 17845449, "collected_count": 3550246, "collector_count": 4511, "show": { "title": "The Daily Show with Jon Stewart", "year": 1996, "ids": { "trakt": 2211, "slug": "the-daily-show-with-jon-stewart", "tvdb": 71256, "imdb": "tt0115147", "tmdb": 2224 } } }, { "watcher_count": 53775, "play_count": 12379465, "collected_count": 3347336, "collector_count": 16230, "show": { "title": "Friends", "year": 1994, "ids": { "trakt": 1657, "slug": "friends", "tvdb": 79168, "imdb": "tt0108778", "tmdb": 1668 } } }, { "watcher_count": 68267, "play_count": 11294835, "collected_count": 3119930, "collector_count": 24399, "show": { "title": "Supernatural", "year": 2005, "ids": { "trakt": 1611, "slug": "supernatural", "tvdb": 78901, "imdb": "tt0460681", "tmdb": 1622 } } }, { "watcher_count": 163097, "play_count": 9945882, "collected_count": 2423833, "collector_count": 57617, "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 1393, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } }, { "watcher_count": 46170, "play_count": 9766448, "collected_count": 2251539, "collector_count": 17682, "show": { "title": "Grey's Anatomy", "year": 2005, "ids": { "trakt": 1407, "slug": "grey-s-anatomy", "tvdb": 73762, "imdb": "tt0413573", "tmdb": 1416 } } }, { "watcher_count": 54604, "play_count": 8986802, "collected_count": 2546116, "collector_count": 20113, "show": { "title": "House", "year": 2004, "ids": { "trakt": 1399, "slug": "house", "tvdb": 73255, "imdb": "tt0412142", "tmdb": 1408 } } }, { "watcher_count": 203742, "play_count": 8784154, "collected_count": 2436824, "collector_count": 73224, "show": { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 1390, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } } } ] ## Watched [/shows/watched/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most watched shows [GET] #### 📄 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`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "watcher_count": 203742, "play_count": 8784154, "collected_count": 2436824, "collector_count": 73224, "show": { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 1390, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } } }, { "watcher_count": 163097, "play_count": 9945882, "collected_count": 2423833, "collector_count": 57617, "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 1393, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } }, { "watcher_count": 155291, "play_count": 23542030, "collected_count": 6635583, "collector_count": 54953, "show": { "title": "The Big Bang Theory", "year": 2007, "ids": { "trakt": 1409, "slug": "the-big-bang-theory", "tvdb": 80379, "imdb": "tt0898266", "tmdb": 1418 } } }, { "watcher_count": 140725, "play_count": 8576210, "collected_count": 2471061, "collector_count": 49385, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1388, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "watcher_count": 123797, "play_count": 6173692, "collected_count": 1856666, "collector_count": 43351, "show": { "title": "Arrow", "year": 2012, "ids": { "trakt": 1403, "slug": "arrow", "tvdb": 257655, "imdb": "tt2193021", "tmdb": 1412 } } }, { "watcher_count": 100242, "play_count": 19787304, "collected_count": 4529880, "collector_count": 32335, "show": { "title": "How I Met Your Mother", "year": 2005, "ids": { "trakt": 1095, "slug": "how-i-met-your-mother", "tvdb": 75760, "imdb": "tt0460649", "tmdb": 1100 } } }, { "watcher_count": 94282, "play_count": 912066, "collected_count": 260713, "collector_count": 34077, "show": { "title": "Sherlock", "year": 2010, "ids": { "trakt": 19792, "slug": "sherlock", "tvdb": 176941, "imdb": "tt1475582", "tmdb": 19885 } } }, { "watcher_count": 89242, "play_count": 3375660, "collected_count": 1299956, "collector_count": 39724, "show": { "title": "Homeland", "year": 2011, "ids": { "trakt": 1398, "slug": "homeland", "tvdb": 247897, "imdb": "tt1796960", "tmdb": 1407 } } }, { "watcher_count": 87059, "play_count": 7799337, "collected_count": 2239477, "collector_count": 33424, "show": { "title": "Dexter", "year": 2006, "ids": { "trakt": 1396, "slug": "dexter", "tvdb": 79349, "imdb": "tt0773262", "tmdb": 1405 } } }, { "watcher_count": 83087, "play_count": 2795758, "collected_count": 881552, "collector_count": 31982, "show": { "title": "Marvel's Agents of S.H.I.E.L.D.", "year": 2013, "ids": { "trakt": 1394, "slug": "marvel-s-agents-of-s-h-i-e-l-d", "tvdb": 263365, "imdb": "tt2364582", "tmdb": 1403 } } } ] ## Collected [/shows/collected/{period}] + Parameters + period (optional, string, `weekly`) ... Time period. + Values + `daily` + `weekly` + `monthly` + `all` ### Get the most collected shows [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most collected (unique users) shows in the specified time `period`, defaulting to `weekly`. All stats are relative to the specific time `period`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "watcher_count": 56216, "play_count": 19286818, "collected_count": 7427018, "collector_count": 23876, "show": { "title": "The Simpsons", "year": 1989, "ids": { "trakt": 455, "slug": "the-simpsons", "tvdb": 71663, "imdb": "tt0096697", "tmdb": 456 } } }, { "watcher_count": 155291, "play_count": 23542030, "collected_count": 6635583, "collector_count": 54953, "show": { "title": "The Big Bang Theory", "year": 2007, "ids": { "trakt": 1409, "slug": "the-big-bang-theory", "tvdb": 80379, "imdb": "tt0898266", "tmdb": 1418 } } }, { "watcher_count": 100242, "play_count": 19787304, "collected_count": 4529880, "collector_count": 32335, "show": { "title": "How I Met Your Mother", "year": 2005, "ids": { "trakt": 1095, "slug": "how-i-met-your-mother", "tvdb": 75760, "imdb": "tt0460649", "tmdb": 1100 } } }, { "watcher_count": 8050, "play_count": 17845449, "collected_count": 3550246, "collector_count": 4511, "show": { "title": "The Daily Show with Jon Stewart", "year": 1996, "ids": { "trakt": 2211, "slug": "the-daily-show-with-jon-stewart", "tvdb": 71256, "imdb": "tt0115147", "tmdb": 2224 } } }, { "watcher_count": 53775, "play_count": 12379465, "collected_count": 3347336, "collector_count": 16230, "show": { "title": "Friends", "year": 1994, "ids": { "trakt": 1657, "slug": "friends", "tvdb": 79168, "imdb": "tt0108778", "tmdb": 1668 } } }, { "watcher_count": 48984, "play_count": 7879681, "collected_count": 3273255, "collector_count": 23114, "show": { "title": "Family Guy", "year": 1999, "ids": { "trakt": 1425, "slug": "family-guy", "tvdb": 75978, "imdb": "tt0182576", "tmdb": 1434 } } }, { "watcher_count": 68267, "play_count": 11294835, "collected_count": 3119930, "collector_count": 24399, "show": { "title": "Supernatural", "year": 2005, "ids": { "trakt": 1611, "slug": "supernatural", "tvdb": 78901, "imdb": "tt0460681", "tmdb": 1622 } } }, { "watcher_count": 41844, "play_count": 7267474, "collected_count": 2965842, "collector_count": 19450, "show": { "title": "South Park", "year": 1997, "ids": { "trakt": 2177, "slug": "south-park", "tvdb": 75897, "imdb": "tt0121955", "tmdb": 2190 } } }, { "watcher_count": 72285, "play_count": 7997522, "collected_count": 2570535, "collector_count": 28446, "show": { "title": "Modern Family", "year": 2009, "ids": { "trakt": 1412, "slug": "modern-family", "tvdb": 95011, "imdb": "tt1442437", "tmdb": 1421 } } }, { "watcher_count": 54604, "play_count": 8986802, "collected_count": 2546116, "collector_count": 20113, "show": { "title": "House", "year": 2004, "ids": { "trakt": 1399, "slug": "house", "tvdb": 73255, "imdb": "tt0412142", "tmdb": 1408 } } } ] ## Anticipated [/shows/anticipated] ### Get the most anticipated shows [GET] #### 📄 Pagination ✨ Extended Info 🎚 Filters Returns the most anticipated shows based on the number of lists a show appears on. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "list_count": 5383, "show": { "title": "Supergirl", "year": 2015, "ids": { "trakt": 99046, "slug": "supergirl", "tvdb": 295759, "imdb": "tt4016454", "tmdb": 62688 } } }, { "list_count": 3132, "show": { "title": "Marvel's Jessica Jones", "year": 2015, "ids": { "trakt": 79385, "slug": "marvel-s-jessica-jones", "tvdb": 284190, "imdb": "tt2357547", "tmdb": 38472 } } }, { "list_count": 3095, "show": { "title": "Lucifer", "year": 2016, "ids": { "trakt": 98990, "slug": "lucifer", "tvdb": 295685, "imdb": "tt4052886", "tmdb": 63174 } } }, { "list_count": 1704, "show": { "title": "Ash vs Evil Dead", "year": 2015, "ids": { "trakt": 99460, "slug": "ash-vs-evil-dead", "tvdb": 296295, "imdb": "tt4189022", "tmdb": 62264 } } }, { "list_count": 1655, "show": { "title": "The Expanse", "year": 2015, "ids": { "trakt": 77199, "slug": "the-expanse", "tvdb": 280619, "imdb": "tt3230854", "tmdb": null } } }, { "list_count": 1481, "show": { "title": "Into the Badlands", "year": 2015, "ids": { "trakt": 82217, "slug": "into-the-badlands", "tvdb": 289079, "imdb": "tt3865236", "tmdb": 47450 } } }, { "list_count": 1332, "show": { "title": "Colony", "year": 2016, "ids": { "trakt": 95966, "slug": "colony", "tvdb": 284210, "imdb": "tt4209256", "tmdb": 62858 } } }, { "list_count": 1060, "show": { "title": "Wicked City", "year": 2015, "ids": { "trakt": 98888, "slug": "wicked-city", "tvdb": 295518, "imdb": "tt4428124", "tmdb": 62927 } } }, { "list_count": 982, "show": { "title": "Marvel's Luke Cage", "year": 2016, "ids": { "trakt": 79382, "slug": "marvel-s-luke-cage", "tvdb": 284192, "imdb": "tt3322314", "tmdb": 62126 } } }, { "list_count": 838, "show": { "title": "Dr. Ken", "year": 2015, "ids": { "trakt": 98913, "slug": "dr-ken-1969", "tvdb": 295557, "imdb": "tt3216608", "tmdb": 62776 } } } ] ## Updates [/shows/updates/{start_date}] + Parameters + start_date (optional, string, `2020-11-27T00:00:00Z`) ... Updated since this date and time. ### Get recently updated shows [GET] #### 📄 Pagination ✨ Extended Info Returns all shows updated since the specified UTC date and time. We recommended storing the `X-Start-Date` header you can be efficient using this method moving forward. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _The `start_date` is only accurate to the hour, for caching purposes. Please drop the minutes and seconds from your timestamp to help optimize our cached data. For example, use `2021-07-17T12:00:00Z` and not `2021-07-17T12:23:34Z`._ > ### 🅽🅾🆃🅴 > _The `start_date` can only be a maximum of 30 days in the past._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: 2020-11-27T00:00:00Z X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "updated_at": "2014-09-22T21:56:03.000Z", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "updated_at": "2014-09-23T21:56:03.000Z", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## Updated IDs [/shows/updates/id/{start_date}] + Parameters + start_date (optional, string, `2020-11-27T00:00:00Z`) ... Updated since this date and time. ### Get recently updated show Trakt IDs [GET] #### 📄 Pagination Returns all show Trakt IDs updated since the specified UTC date and time. We recommended storing the `X-Start-Date` header you can be efficient using this method moving forward. By default, `10` results are returned. You can send a `limit` to get up to `100` results per page. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _The `start_date` is only accurate to the hour, for caching purposes. Please drop the minutes and seconds from your timestamp to help optimize our cached data. For example, use `2021-07-17T12:00:00Z` and not `2021-07-17T12:23:34Z`._ > ### 🅽🅾🆃🅴 > _The `start_date` can only be a maximum of 30 days in the past._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Start-Date: 2020-11-27T00:00:00Z X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ 1, 20, 34, 50 ] ## Summary [/shows/{id}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get a single show [GET] #### ✨ 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. > ### 🅽🅾🆃🅴 > _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`._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /shows/game-of-thrones ``` + Body { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 353, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } } + Response 200 (application/json) ``` /shows/game-of-thrones?extended=full ``` + Body { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 353, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 }, "tagline": "Winter Is Coming", "overview": "Game of Thrones is an American fantasy drama television series created for HBO by David Benioff and D. B. Weiss. It is an adaptation of A Song of Ice and Fire, George R. R. Martin's series of fantasy novels, the first of which is titled A Game of Thrones.\n\nThe series, set on the fictional continents of Westeros and Essos at the end of a decade-long summer, interweaves several plot lines. The first follows the members of several noble houses in a civil war for the Iron Throne of the Seven Kingdoms; the second covers the rising threat of the impending winter and the mythical creatures of the North; the third chronicles the attempts of the exiled last scion of the realm's deposed dynasty to reclaim the throne. Through its morally ambiguous characters, the series explores the issues of social hierarchy, religion, loyalty, corruption, sexuality, civil war, crime, and punishment.", "first_aired": "2011-04-18T01:00:00.000Z", "airs": { "day": "Sunday", "time": "21:00", "timezone": "America/New_York" }, "runtime": 60, "total_runtime": 3000, "certification": "TV-MA", "network": "HBO", "country": "us", "updated_at": "2014-08-22T08:32:06.000Z", "trailer": null, "homepage": "http://www.hbo.com/game-of-thrones/index.html", "status": "returning series", "rating": 9.0, "votes": 111, "comment_count": 92, "languages": ["en"], "available_translations": ["en", "tr", "sk", "de", "ru", "fr", "hu", "zh", "el", "pt", "es", "bg", "ro", "it", "ko", "he", "nl", "pl"], "genres": ["drama", "fantasy"], "aired_episodes": 50, "original_title": "Game of Thrones" } ## Aliases [/shows/{id}/aliases] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all show aliases [GET] Returns all title aliases for a show. Includes country where name is different. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title": "冰與火之歌：權力遊戲", "country": "tw" }, { "title": "A Guerra dos Tronos", "country": "br" }, { "title": "Game of Thrones- Das Lied von Eis und Feuer", "country": "de" }, { "title": "Παιχνίδι Του Στέμματος", "country": "gr" }, { "title": "Game of Thrones - Das Lied von Eis und Feuer", "country": "de" }, { "title": "Le Trône de fer", "country": "fr" }, { "title": "Urzeala Tronurilor", "country": "ro" }, { "title": "صراع العروش", "country": "sa" } ] ## Certifications [/shows/{id}/certifications] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all show certifications [GET] Returns all content certifications for a show, including the country. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "certification":"TV-MA", "country":"us" }, { "certification":"12", "country":"de" }, { "certification":"15", "country":"kr" }, { "certification":"15", "country":"gb" }, { "certification":"16", "country":"br" }, { "certification":"12", "country":"nl" }, { "certification":"18", "country":"pt" } ] ## Translations [/shows/{id}/translations/{language}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + language (optional, string, `es`) ... 2 character language code ### Get all show translations [GET] 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`). + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title": "Breaking Bad", "overview": "Breaking Bad is an American crime drama television series created and produced by Vince Gilligan. Set and produced in Albuquerque, New Mexico, Breaking Bad is the story of Walter White, a struggling high school chemistry teacher who is diagnosed with inoperable lung cancer at the beginning of the series. He turns to a life of crime, producing and selling methamphetamine, in order to secure his family's financial future before he dies, teaming with his former student, Jesse Pinkman. Heavily serialized, the series is known for positioning its characters in seemingly inextricable corners and has been labeled a contemporary western by its creator.", "tagline": "Change the equation.", "language": "en", "country": "us" }, { "title": "Breaking Bad", "overview": "...", "tagline": "...", "language": "tr", "country": "tr" }, { "title": "Perníkový tatko", "overview": "", "tagline": null, "language": "sk", "country": "sk" } ] ## Comments [/shows/{id}/comments/{sort}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `watched` + `plays` + `rating` + `added` ### Get all show comments [GET] #### 🔓 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Great show!", "spoiler": false, "review": false, "replies": 1, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Lists [/shows/{id}/lists/{type}/{sort}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + type (optional, string, `personal`) ... Filter for a specific list type + Values + `all` + `personal` + `official` + `watchlists` + `favorites` + sort (optional, string, `popular`) ... How to sort + Values + `popular` + `likes` + `comments` + `items` + `added` + `updated` ### Get lists containing this show [GET] #### 📄 Pagination 😁 Emojis Returns all lists that contain this show. By default, `personal` lists are returned sorted by the most `popular`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "name": "Incredible Thoughts", "description": "How could my brain conceive them?", "privacy": "public", "share_link": "https://trakt.tv/lists/1337", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 10, "likes": 99, "ids": { "trakt": 1337, "slug": "incredible-thoughts" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## Collection Progress [/shows/{id}/progress/collection{?hidden,specials,count_specials,last_activity}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + hidden (optional, string, `false`) ... include any hidden seasons + specials (optional, string, `false`) ... include specials as season 0 + count_specials (optional, string, `true`) ... count specials in the overall stats (only applies if specials are included) + last_activity (optional, string, `aired`) ... used to calculate last_episode and next_episode + Values + `aired` + `collected` ### Get show collection progress [GET] #### 🔒 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`. 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 collected, even if they've collected older episodes more recently. To use their last collected episode for these calculations, set the `last_activity` flag to `collected`. > ### 🅽🅾🆃🅴 > _Only aired episodes are used to calculate progress. Episodes in the future or without an air date are ignored._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "aired": 8, "completed": 6, "last_collected_at": "2015-03-21T19:03:58.000Z", "seasons": [ { "number": 1, "title": "The first Hodor.", "aired": 8, "completed": 6, "episodes": [ { "number": 1, "completed": true, "collected_at": "2015-03-21T19:03:58.000Z" }, { "number": 2, "completed": true, "collected_at": "2015-03-21T19:03:58.000Z" }, { "number": 3, "completed": true, "collected_at": "2015-03-21T19:03:58.000Z" }, { "number": 4, "completed": true, "collected_at": "2015-03-21T19:03:58.000Z" }, { "number": 5, "completed": true, "collected_at": "2015-03-21T19:03:58.000Z" }, { "number": 6, "completed": true, "collected_at": "2015-03-21T19:03:58.000Z" }, { "number": 7, "completed": false, "collected_at": null }, { "number": 8, "completed": false, "collected_at": null } ] } ], "hidden_seasons": [ { "number": 2, "ids": { "trakt": 3051, "tvdb": 498968, "tmdb": 53334 } } ], "next_episode": { "season": 1, "number": 7, "title": "Water", "ids": { "trakt": 62315, "tvdb": 4849873, "imdb": null, "tmdb": null } }, "last_episode": { "season": 1, "number": 6, "title": "Fire", "ids": { "trakt": 62314, "tvdb": 4849872, "imdb": null, "tmdb": null } } } ## Watched Progress [/shows/{id}/progress/watched{?hidden,specials,count_specials,last_activity}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + hidden (optional, string, `false`) ... include any hidden seasons + specials (optional, string, `false`) ... include specials as season 0 + count_specials (optional, string, `true`) ... count specials in the overall stats (only applies if specials are included) + last_activity (optional, string, `aired`) ... used to calculate last_episode and next_episode + Values + `aired` + `watched` ### Get show watched progress [GET] #### 🔒 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`. > ### 🅽🅾🆃🅴 > _Only aired episodes are used to calculate progress. Episodes in the future or without an air date are ignored._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "aired": 8, "completed": 6, "last_watched_at": "2015-03-21T19:03:58.000Z", "reset_at": null, "seasons": [ { "number": 1, "title": "The first Hodor.", "aired": 8, "completed": 6, "episodes": [ { "number": 1, "completed": true, "last_watched_at": "2015-03-21T19:03:58.000Z" }, { "number": 2, "completed": true, "last_watched_at": "2015-03-21T19:03:58.000Z" }, { "number": 3, "completed": true, "last_watched_at": "2015-03-21T19:03:58.000Z" }, { "number": 4, "completed": true, "last_watched_at": "2015-03-21T19:03:58.000Z" }, { "number": 5, "completed": true, "last_watched_at": "2015-03-21T19:03:58.000Z" }, { "number": 6, "completed": true, "last_watched_at": "2015-03-21T19:03:58.000Z" }, { "number": 7, "completed": false, "last_watched_at": null }, { "number": 8, "completed": false, "last_watched_at": null } ] } ], "hidden_seasons": [ { "number": 2, "ids": { "trakt": 3051, "tvdb": 498968, "tmdb": 53334 } } ], "next_episode": { "season": 1, "number": 7, "title": "Water", "ids": { "trakt": 62315, "tvdb": 4849873, "imdb": null, "tmdb": null } }, "last_episode": { "season": 1, "number": 6, "title": "Fire", "ids": { "trakt": 62314, "tvdb": 4849872, "imdb": null, "tmdb": null } } } ## Reset Watched Progress [/shows/{id}/progress/watched/reset] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Reset show progress [POST] #### 🔥 VIP Only 🔒 OAuth Required Reset a show's progress when the user started re-watching the show. You can optionally specify the `reset_at` date to have it calculate progress from that specific date onwards. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "reset_at": "2021-07-01T00:00:000Z" } ### Undo reset show progress [DELETE] #### 🔥 VIP Only 🔒 OAuth Required Undo the reset and have watched progress use all watched history for the show. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ## People [/shows/{id}/people] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all people for a show [GET] #### ✨ 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. > ### 🅽🅾🆃🅴 > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /shows/game-of-thrones/people ``` + Body { "cast":[ { "characters":["Daenerys Targaryen"], "episode_count":73, "person":{ "name":"Emilia Clarke", "ids":{ "trakt":2332, "slug":"emilia-clarke", "imdb":"nm3592338", "tmdb":1223786 } } }, { "characters":["Varys"], "episode_count":73, "person":{ "name":"Conleth Hill", "ids":{ "trakt":4428, "slug":"conleth-hill", "imdb":"nm0384152", "tmdb":84423 } } }, { "characters":["Tyrion Lannister"], "episode_count":73, "person":{ "name":"Peter Dinklage", "ids":{ "trakt":2329, "slug":"peter-dinklage", "imdb":"nm0227759", "tmdb":22970 } } } ], "crew":{ "art":[ { "jobs":["Production Design"], "episode_count":30, "person":{ "name":"Gemma Jackson", "ids":{ "trakt":17454, "slug":"gemma-jackson", "imdb":"nm0413541", "tmdb":9153 } } }, { "jobs":["Art Direction"], "episode_count":20, "person":{ "name":"Philip Elton", "ids":{ "trakt":13414, "slug":"philip-elton", "imdb":"nm0255797", "tmdb":80424 } } } ], "production":[ { "jobs":["Co-Executive Producer"], "episode_count":73, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } }, { "jobs":["Executive Producer"], "episode_count":73, "person":{ "name":"D. B. Weiss", "ids":{ "trakt":17443, "slug":"d-b-weiss", "imdb":"nm1888967", "tmdb":228068 } } } ], "sound":[ { "jobs":["Original Music Composer"], "episode_count":73, "person":{ "name":"Ramin Djawadi", "ids":{ "trakt":3698, "slug":"ramin-djawadi", "imdb":"nm1014697", "tmdb":10851 } } }, { "jobs":["Sound Designer"], "episode_count":40, "person":{ "name":"Paula Fairfield", "ids":{ "trakt":17461, "slug":"paula-fairfield", "imdb":"nm0265584", "tmdb":85960 } } } ], "visual effects":[ { "jobs":["Visual Effects"], "episode_count":10, "person":{ "name":"Jeremy Stewart", "ids":{ "trakt":5018, "slug":"jeremy-stewart", "imdb":"nm2108603", "tmdb":1463785 } } } ], "costume & make-up":[ { "jobs":["Costume Design"], "episode_count":63, "person":{ "name":"Michele Clapton", "ids":{ "trakt":5019, "slug":"michele-clapton", "imdb":"nm0163449", "tmdb":50953 } } } ], "writing":[ { "jobs":["Novel"], "episode_count":73, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } } ], "directing":[ { "jobs":["Director"], "episode_count":9, "person":{ "name":"David Nutter", "ids":{ "trakt":346, "slug":"david-nutter", "imdb":"nm0638354", "tmdb":33316 } } }, { "jobs":["Director"], "episode_count":7, "person":{ "name":"Alan Taylor", "ids":{ "trakt":17457, "slug":"alan-taylor", "imdb":"nm0851930", "tmdb":47005 } } } ] } } + Response 200 (application/json) ``` /shows/game-of-thrones/people?extended=guest_stars ``` + Body { "cast":[ { "characters":["Daenerys Targaryen"], "episode_count":73, "person":{ "name":"Emilia Clarke", "ids":{ "trakt":2332, "slug":"emilia-clarke", "imdb":"nm3592338", "tmdb":1223786 } } }, { "characters":["Varys"], "episode_count":73, "person":{ "name":"Conleth Hill", "ids":{ "trakt":4428, "slug":"conleth-hill", "imdb":"nm0384152", "tmdb":84423 } } }, { "characters":["Tyrion Lannister"], "episode_count":73, "person":{ "name":"Peter Dinklage", "ids":{ "trakt":2329, "slug":"peter-dinklage", "imdb":"nm0227759", "tmdb":22970 } } } ], "guest_stars":[ { "characters":["Podrick Payne"], "episode_count":33, "person":{ "name":"Daniel Portman", "ids":{ "trakt":13094, "slug":"daniel-portman", "imdb":"nm4535552", "tmdb":1034702 } } }, { "characters":["Eddison Tollett"], "episode_count":32, "person":{ "name":"Ben Crompton", "ids":{ "trakt":1782, "slug":"ben-crompton", "imdb":"nm0174005", "tmdb":72315 } } }, { "characters":["Grand Maester Pycelle"], "episode_count":31, "person":{ "name":"Julian Glover", "ids":{ "trakt":2654, "slug":"julian-glover", "imdb":"nm0002103", "tmdb":740 } } } ], "crew":{ "art":[ { "jobs":["Production Design"], "episode_count":30, "person":{ "name":"Gemma Jackson", "ids":{ "trakt":17454, "slug":"gemma-jackson", "imdb":"nm0413541", "tmdb":9153 } } }, { "jobs":["Art Direction"], "episode_count":20, "person":{ "name":"Philip Elton", "ids":{ "trakt":13414, "slug":"philip-elton", "imdb":"nm0255797", "tmdb":80424 } } } ], "production":[ { "jobs":["Co-Executive Producer"], "episode_count":73, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } }, { "jobs":["Executive Producer"], "episode_count":73, "person":{ "name":"D. B. Weiss", "ids":{ "trakt":17443, "slug":"d-b-weiss", "imdb":"nm1888967", "tmdb":228068 } } } ], "sound":[ { "jobs":["Original Music Composer"], "episode_count":73, "person":{ "name":"Ramin Djawadi", "ids":{ "trakt":3698, "slug":"ramin-djawadi", "imdb":"nm1014697", "tmdb":10851 } } }, { "jobs":["Sound Designer"], "episode_count":40, "person":{ "name":"Paula Fairfield", "ids":{ "trakt":17461, "slug":"paula-fairfield", "imdb":"nm0265584", "tmdb":85960 } } } ], "visual effects":[ { "jobs":["Visual Effects"], "episode_count":10, "person":{ "name":"Jeremy Stewart", "ids":{ "trakt":5018, "slug":"jeremy-stewart", "imdb":"nm2108603", "tmdb":1463785 } } } ], "costume & make-up":[ { "jobs":["Costume Design"], "episode_count":63, "person":{ "name":"Michele Clapton", "ids":{ "trakt":5019, "slug":"michele-clapton", "imdb":"nm0163449", "tmdb":50953 } } } ], "writing":[ { "jobs":["Novel"], "episode_count":73, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } } ], "directing":[ { "jobs":["Director"], "episode_count":9, "person":{ "name":"David Nutter", "ids":{ "trakt":346, "slug":"david-nutter", "imdb":"nm0638354", "tmdb":33316 } } }, { "jobs":["Director"], "episode_count":7, "person":{ "name":"Alan Taylor", "ids":{ "trakt":17457, "slug":"alan-taylor", "imdb":"nm0851930", "tmdb":47005 } } } ] } } ## Ratings [/shows/{id}/ratings] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get show ratings [GET] Returns rating (between 0 and 10) and distribution for a show. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "rating": 9.38363, "votes": 51065, "distribution": { "1": 320, "2": 77, "3": 73, "4": 131, "5": 300, "6": 514, "7": 1560, "8": 4399, "9": 9648, "10": 34042 } } ## Related [/shows/{id}/related] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get related shows [GET] #### 📄 Pagination ✨ Extended Info Returns related and similar shows. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "title": "Battlestar Galactica", "year": 2005, "ids": { "trakt": 331, "slug": "battlestar-galactica", "tvdb": 73545, "imdb": "tt0407362", "tmdb": 1972 } }, { "title": "Game of Thrones", "year": 2011, "ids": { "trakt": 353, "slug": "game-of-thrones", "tvdb": 121361, "imdb": "tt0944947", "tmdb": 1399 } }, { "title": "Firefly", "year": 2002, "ids": { "trakt": 329, "slug": "firefly", "tvdb": 78874, "imdb": "tt0303461", "tmdb": 1437 } }, { "title": "The Newsroom", "year": 2012, "ids": { "trakt": 497, "slug": "the-newsroom", "tvdb": 256227, "imdb": "tt1870479", "tmdb": 15621 } }, { "title": "Dollhouse", "year": 2009, "ids": { "trakt": 395, "slug": "dollhouse", "tvdb": 82046, "imdb": "tt1135300", "tmdb": 14956 } }, { "title": "Sons of Anarchy", "year": 2008, "ids": { "trakt": 23, "slug": "sons-of-anarchy", "tvdb": 82696, "imdb": "tt1124373", "tmdb": 1409 } }, { "title": "Hannibal", "year": 2013, "ids": { "trakt": 567, "slug": "hannibal", "tvdb": 259063, "imdb": "tt2243973", "tmdb": 40008 } }, { "title": "True Blood", "year": 2008, "ids": { "trakt": 122, "slug": "true-blood", "tvdb": 82283, "imdb": "tt0844441", "tmdb": 10545 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } }, { "title": "The Shield", "year": 2002, "ids": { "trakt": 486, "slug": "the-shield", "tvdb": 78261, "imdb": "tt0286486", "tmdb": 1414 } } ] ## Stats [/shows/{id}/stats] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get show stats [GET] Returns lots of show stats. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "watchers": 355422, "plays": 18278737, "collectors": 159266, "collected_episodes": 7144637, "comments": 257, "lists": 149488, "votes": 51065, "favorited": 54321 } ## Studios [/shows/{id}/studios] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get show studios [GET] Returns all studios for a show. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "name":"ABC Studios", "country":"us", "ids":{ "trakt":1, "slug":"abc-studios", "tmdb":19366 } }, { "name":"DeKnight Productions", "country":"us", "ids":{ "trakt":2, "slug":"deknight-productions", "tmdb":51963 } }, { "name":"Goddard Textiles", "country":"us", "ids":{ "trakt":3, "slug":"goddard-textiles", "tmdb":51964 } }, { "name":"Marvel Television", "country":"us", "ids":{ "trakt":4, "slug":"marvel-television", "tmdb":38679 } } ] ## Watching [/shows/{id}/watching] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get users watching right now [GET] #### ✨ Extended Info Returns all users watching this show right now. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } }, { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } ] ## Next Episode [/shows/{id}/next_episode] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get next episode [GET] #### ✨ Extended Info Returns the next scheduled to air episode. If no episode is found, a `204` HTTP status code will be returned. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "season": 7, "number": 1, "title": "TBA", "ids": { "trakt": 2279059, "tvdb": 5773656, "imdb": null, "tmdb": null } } ## Last Episode [/shows/{id}/last_episode] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get last episode [GET] #### ✨ Extended Info Returns the most recently aired episode. If no episode is found, a `204` HTTP status code will be returned. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "season": 6, "number": 10, "title": "The Winds of Winter", "ids": { "trakt": 1989031, "tvdb": 5624261, "imdb": "tt4283094", "tmdb": 1187405 } } ## Videos [/shows/{id}/videos] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all videos [GET] #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title":"Official Trailer # 3", "url":"https://youtube.com/watch?v=d4RiUy23e9s", "site":"youtube", "type":"trailer", "size":1080, "official":true, "published_at":"2010-11-09T01:07:39.000Z", "country":"us", "language":"en" } ] ## Refresh [/shows/{id}/refresh] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Refresh show metadata [POST] #### 🔥 VIP Only 🔒 OAuth Required Queue this show for a full metadata and image refresh. It might take up to 8 hours for the updated metadata to be availabe through the API. > ### 🅽🅾🆃🅴 > _If this show is already queued, a `409` HTTP status code will returned._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 201 (application/json) ## Report [/shows/{id}/report] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Report a show [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "metadata", "message": "Wrong network is listed." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: duplicate, remove, data_refresh, metadata, adult, runtime, language, spam, tmdb, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } # Group Seasons ## Summary [/shows/{id}/seasons] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID ### Get all seasons for a show [GET] #### ✨ 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. > ### 🅽🅾🆃🅴 > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /shows/game-of-thrones/seasons ``` + Body [ { "number": 0, "ids": { "trakt": 1, "tvdb": 137481, "tmdb": 3627 } }, { "number": 1, "ids": { "trakt": 2, "tvdb": 364731, "tmdb": 3624 } }, { "number": 2, "ids": { "trakt": 3, "tvdb": 473271, "tmdb": 3625 } }, { "number": 3, "ids": { "trakt": 4, "tvdb": 488434, "tmdb": 3626 } }, { "number": 4, "ids": { "trakt": 5, "tvdb": 522882, "tmdb": 3628 } } ] + Response 200 (application/json) ``` /shows/game-of-thrones/seasons?extended=full ``` + Body [ { "number": 0, "ids": { "trakt": 1, "tvdb": 137481, "tmdb": 3627 }, "rating": 9.0, "votes": 111, "episode_count": 10, "aired_episodes": 10, "total_runtime": 600, "title": "Specials", "overview": null, "first_aired": "2010-12-06T02:00:00.000Z", "udpated_at": "2010-12-07T01:023:00.000Z", "network": "HBO", "original_title": null }, { "number": 1, "ids": { "trakt": 2, "tvdb": 364731, "tmdb": 3624 }, "rating": 9.0, "votes": 111, "episode_count": 10, "aired_episodes": 10, "total_runtime": 600, "title": "Season 1", "overview": "Season 1 overview.", "first_aired": "2011-04-09T02:00:00.000Z", "udpated_at": "2010-12-07T01:023:00.000Z", "network": "HBO", "original_title": "Season 1" }, { "number": 2, "ids": { "trakt": 3, "tvdb": 473271, "tmdb": 3625 }, "rating": 9.0, "votes": 111, "episode_count": 10, "aired_episodes": 10, "total_runtime": 600, "title": "Season 2", "overview": "Season 2 overview.", "first_aired": "2012-04-02T02:00:00.000Z", "udpated_at": "2010-12-07T01:023:00.000Z", "network": "HBO", "original_title": null }, { "number": 3, "ids": { "trakt": 4, "tvdb": 488434, "tmdb": 3626 }, "rating": 9.0, "votes": 111, "episode_count": 10, "aired_episodes": 10, "total_runtime": 600, "title": "Season 3", "overview": "Season 3 overview.", "first_aired": "2013-04-01T02:00:00.000Z", "udpated_at": "2010-12-07T01:023:00.000Z", "network": "HBO", "original_title": null }, { "number": 4, "ids": { "trakt": 5, "tvdb": 522882, "tmdb": 3628 }, "rating": 9.0, "votes": 111, "episode_count": 10, "aired_episodes": 10, "total_runtime": 600, "title": "Season 4", "overview": "Season 4 overview", "first_aired": "2014-04-07T02:00:00.000Z", "udpated_at": "2010-12-07T01:023:00.000Z", "network": "HBO", "original_title": null } ] + Response 200 (application/json) ``` /shows/game-of-thrones/seasons?extended=episodes ``` + Body [ { "number": 0, "ids": { "trakt": 2145, "tvdb": 137481, "tmdb": 3627 }, "episodes": [ { "season": 0, "number": 1, "title": "Inside Game of Thrones", "ids": { "trakt": 36430, "tvdb": 3226241, "imdb": "", "tmdb": 63087 } }, { "season": 0, "number": 2, "title": "15-Minute Preview", "ids": { "trakt": 36431, "tvdb": 4045941, "imdb": "", "tmdb": 63086 } }, { "season": 0, "number": 3, "title": "Making Game of Thrones", "ids": { "trakt": 36432, "tvdb": 4073401, "imdb": "", "tmdb": 63088 } }, { "season": 0, "number": 4, "title": "El Juego Comienza", "ids": { "trakt": 36433, "tvdb": 4082317, "imdb": "", "tmdb": 63089 } }, { "season": 0, "number": 5, "title": "2011 Comic Con Panel", "ids": { "trakt": 36434, "tvdb": 4138149, "imdb": "", "tmdb": 63090 } }, { "season": 0, "number": 6, "title": "You Win or You Die", "ids": { "trakt": 36435, "tvdb": 4292422, "imdb": "", "tmdb": 63091 } }, { "season": 0, "number": 7, "title": "A Gathering Storm", "ids": { "trakt": 36436, "tvdb": 4517457, "imdb": "", "tmdb": 63092 } }, { "season": 0, "number": 8, "title": "Politics of Marriage", "ids": { "trakt": 36437, "tvdb": 4576208, "imdb": "", "tmdb": 63093 } }, { "season": 0, "number": 9, "title": "Ice and Fire: A Foreshadowing", "ids": { "trakt": 36438, "tvdb": 4779102, "imdb": "", "tmdb": 974558 } }, { "season": 0, "number": 10, "title": "The Politics of Power: A Look Back at Season 3", "ids": { "trakt": 36439, "tvdb": 4824480, "imdb": "", "tmdb": 974559 } } ] }, { "number": 1, "ids": { "trakt": 2146, "tvdb": 364731, "tmdb": 3624 }, "episodes": [ { "season": 1, "number": 1, "title": "Winter Is Coming", "ids": { "trakt": 36440, "tvdb": 3254641, "imdb": "tt1480055", "tmdb": 63056 } }, { "season": 1, "number": 2, "title": "The Kingsroad", "ids": { "trakt": 36441, "tvdb": 3436411, "imdb": "tt1668746", "tmdb": 63057 } }, { "season": 1, "number": 3, "title": "Lord Snow", "ids": { "trakt": 36442, "tvdb": 3436421, "imdb": "tt1829962", "tmdb": 63058 } }, { "season": 1, "number": 4, "title": "Cripples, Bastards, and Broken Things", "ids": { "trakt": 36443, "tvdb": 3436431, "imdb": "tt1829963", "tmdb": 63059 } }, { "season": 1, "number": 5, "title": "The Wolf and the Lion", "ids": { "trakt": 36444, "tvdb": 3436441, "imdb": "tt1829964", "tmdb": 63060 } }, { "season": 1, "number": 6, "title": "A Golden Crown", "ids": { "trakt": 36445, "tvdb": 3436451, "imdb": "tt1837862", "tmdb": 63061 } }, { "season": 1, "number": 7, "title": "You Win or You Die", "ids": { "trakt": 36446, "tvdb": 3436461, "imdb": "tt1837863", "tmdb": 63062 } }, { "season": 1, "number": 8, "title": "The Pointy End", "ids": { "trakt": 36447, "tvdb": 3360391, "imdb": "tt1837864", "tmdb": 63063 } }, { "season": 1, "number": 9, "title": "Baelor", "ids": { "trakt": 36448, "tvdb": 4063481, "imdb": "tt1851398", "tmdb": 63064 } }, { "season": 1, "number": 10, "title": "Fire and Blood", "ids": { "trakt": 36449, "tvdb": 4063491, "imdb": "tt1851397", "tmdb": 63065 } } ] }, { "number": 2, "ids": { "trakt": 2147, "tvdb": 473271, "tmdb": 3625 }, "episodes": [ { "season": 2, "number": 1, "title": "The North Remembers", "ids": { "trakt": 36450, "tvdb": 4161693, "imdb": "tt1971833", "tmdb": 63066 } }, { "season": 2, "number": 2, "title": "The Night Lands", "ids": { "trakt": 36451, "tvdb": 4245771, "imdb": "tt2069318", "tmdb": 974430 } }, { "season": 2, "number": 3, "title": "What is Dead May Never Die", "ids": { "trakt": 36452, "tvdb": 4245772, "imdb": "tt2070135", "tmdb": 63068 } }, { "season": 2, "number": 4, "title": "Garden of Bones", "ids": { "trakt": 36453, "tvdb": 4245773, "imdb": "tt2069319", "tmdb": 63069 } }, { "season": 2, "number": 5, "title": "The Ghost of Harrenhal", "ids": { "trakt": 36454, "tvdb": 4245774, "imdb": "tt2074658", "tmdb": 63070 } }, { "season": 2, "number": 6, "title": "The Old Gods and the New", "ids": { "trakt": 36455, "tvdb": 4245775, "imdb": "tt2085238", "tmdb": 63071 } }, { "season": 2, "number": 7, "title": "A Man Without Honor", "ids": { "trakt": 36456, "tvdb": 4245776, "imdb": "tt2085239", "tmdb": 63073 } }, { "season": 2, "number": 8, "title": "The Prince of Winterfell", "ids": { "trakt": 36457, "tvdb": 4245777, "imdb": "tt2085240", "tmdb": 63074 } }, { "season": 2, "number": 9, "title": "Blackwater", "ids": { "trakt": 36458, "tvdb": 4245778, "imdb": "tt2084342", "tmdb": 63072 } }, { "season": 2, "number": 10, "title": "Valar Morghulis", "ids": { "trakt": 36459, "tvdb": 4245779, "imdb": "tt2112510", "tmdb": 63075 } } ] }, { "number": 3, "ids": { "trakt": 2148, "tvdb": 488434, "tmdb": 3626 }, "episodes": [ { "season": 3, "number": 1, "title": "Valar Dohaeris", "ids": { "trakt": 36460, "tvdb": 4293685, "imdb": "tt2178782", "tmdb": 63077 } }, { "season": 3, "number": 2, "title": "Dark Wings, Dark Words", "ids": { "trakt": 36461, "tvdb": 4517458, "imdb": "tt2178772", "tmdb": 63076 } }, { "season": 3, "number": 3, "title": "Walk of Punishment", "ids": { "trakt": 36462, "tvdb": 4517459, "imdb": "tt2178802", "tmdb": 63078 } }, { "season": 3, "number": 4, "title": "And Now His Watch Is Ended", "ids": { "trakt": 36463, "tvdb": 4517460, "imdb": "tt2178798", "tmdb": 63082 } }, { "season": 3, "number": 5, "title": "Kissed by Fire", "ids": { "trakt": 36464, "tvdb": 4517461, "imdb": "tt2178788", "tmdb": 63083 } }, { "season": 3, "number": 6, "title": "The Climb", "ids": { "trakt": 36465, "tvdb": 4517462, "imdb": "tt2178812", "tmdb": 63084 } }, { "season": 3, "number": 7, "title": "The Bear and the Maiden Fair", "ids": { "trakt": 36466, "tvdb": 4517463, "imdb": "tt2178814", "tmdb": 63081 } }, { "season": 3, "number": 8, "title": "Second Sons", "ids": { "trakt": 36467, "tvdb": 4517464, "imdb": "tt2178806", "tmdb": 63085 } }, { "season": 3, "number": 9, "title": "The Rains of Castamere", "ids": { "trakt": 36468, "tvdb": 4517465, "imdb": "tt2178784", "tmdb": 63080 } }, { "season": 3, "number": 10, "title": "Mhysa", "ids": { "trakt": 36469, "tvdb": 4517466, "imdb": "tt2178796", "tmdb": 63079 } } ] }, { "number": 4, "ids": { "trakt": 2149, "tvdb": 522882, "tmdb": 3628 }, "episodes": [ { "season": 4, "number": 1, "title": "Two Swords", "ids": { "trakt": 36470, "tvdb": 4721938, "imdb": "tt2816136", "tmdb": 973190 } }, { "season": 4, "number": 2, "title": "The Lion and the Rose", "ids": { "trakt": 36471, "tvdb": 4801602, "imdb": "tt2832378", "tmdb": 973219 } }, { "season": 4, "number": 3, "title": "Breaker of Chains", "ids": { "trakt": 36472, "tvdb": 4615736, "imdb": "tt2972426", "tmdb": 63096 } }, { "season": 4, "number": 4, "title": "Oathkeeper", "ids": { "trakt": 36473, "tvdb": 4615737, "imdb": "tt2972428", "tmdb": 63097 } }, { "season": 4, "number": 5, "title": "First of His Name", "ids": { "trakt": 36474, "tvdb": 4615738, "imdb": "tt3060856", "tmdb": 63098 } }, { "season": 4, "number": 6, "title": "The Laws of Gods and Men", "ids": { "trakt": 36475, "tvdb": 4615739, "imdb": "tt3060910", "tmdb": 63099 } }, { "season": 4, "number": 7, "title": "Mockingbird", "ids": { "trakt": 36476, "tvdb": 4615740, "imdb": "tt3060876", "tmdb": 63100 } }, { "season": 4, "number": 8, "title": "The Mountain and the Viper", "ids": { "trakt": 36477, "tvdb": 4615741, "imdb": "tt3060782", "tmdb": 63101 } }, { "season": 4, "number": 9, "title": "The Watchers on the Wall", "ids": { "trakt": 36478, "tvdb": 4615742, "imdb": "tt3060858", "tmdb": 63102 } }, { "season": 4, "number": 10, "title": "The Children", "ids": { "trakt": 36479, "tvdb": 4615743, "imdb": "tt3060860", "tmdb": 63103 } } ] }, { "number": 5, "ids": { "trakt": 3955, "tvdb": null, "tmdb": 62090 }, "episodes": [ { "season": 5, "number": 1, "title": "5x1", "ids": { "trakt": 63767, "tvdb": null, "imdb": "", "tmdb": 1001402 } } ] } ] ## Season [/shows/{id}/seasons/{season}/info] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number ### Get single seasons for a show [GET] #### ✨ Extended Info Returns a single seasons for a show. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/info ``` + Body { "number": 1, "ids": { "trakt": 2, "tvdb": 364731, "tmdb": 3624 } } + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/info?extended=full ``` + Body { "number": 1, "ids": { "trakt": 2, "tvdb": 364731, "tmdb": 3624 }, "rating": 9.0, "votes": 111, "episode_count": 10, "aired_episodes": 10, "total_runtime": 600, "title": "Season 1", "overview": "Season 1 overview.", "first_aired": "2011-04-09T02:00:00.000Z", "udpated_at": "2010-12-07T01:023:00.000Z", "network": "HBO", "original_title": "Season 1" } ## Episodes [/shows/{id}/seasons/{season}{?translations}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + translations (optional, string, `es`) ... include episode translations ### Get all episodes for a single season [GET] #### ✨ 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. > ### 🅽🅾🆃🅴 > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "season": 1, "number": 1, "title": "Winter Is Coming", "ids": { "trakt": 456, "tvdb": 3254641, "imdb": "tt1480055", "tmdb": 63056 } }, { "season": 1, "number": 2, "title": "The Kingsroad", "ids": { "trakt": 457, "tvdb": 3436411, "imdb": "tt1668746", "tmdb": 63057 } }, { "season": 1, "number": 3, "title": "Lord Snow", "ids": { "trakt": 458, "tvdb": 3436421, "imdb": "tt1829962", "tmdb": 63058 } }, { "season": 1, "number": 4, "title": "Cripples, Bastards, and Broken Things", "ids": { "trakt": 459, "tvdb": 3436431, "imdb": "tt1829963", "tmdb": 63059 } }, { "season": 1, "number": 5, "title": "The Wolf and the Lion", "ids": { "trakt": 460, "tvdb": 3436441, "imdb": "tt1829964", "tmdb": 63060 } }, { "season": 1, "number": 6, "title": "A Golden Crown", "ids": { "trakt": 461, "tvdb": 3436451, "imdb": "tt1837862", "tmdb": 63061 } }, { "season": 1, "number": 7, "title": "You Win or You Die", "ids": { "trakt": 462, "tvdb": 3436461, "imdb": "tt1837863", "tmdb": 63062 } }, { "season": 1, "number": 8, "title": "The Pointy End", "ids": { "trakt": 463, "tvdb": 3360391, "imdb": "tt1837864", "tmdb": 63063 } }, { "season": 1, "number": 9, "title": "Baelor", "ids": { "trakt": 464, "tvdb": 4063481, "imdb": "tt1851398", "tmdb": 63064 } }, { "season": 1, "number": 10, "title": "Fire and Blood", "ids": { "trakt": 465, "tvdb": 4063491, "imdb": "tt1851397", "tmdb": 63065 } } ] ## Translations [/shows/{id}/seasons/{season}/translations/{language}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + language (optional, string, `es`) ... 2 character language code ### Get all season translations [GET] Returns all translations for a season, 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`). + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title": "시즌 1", "overview": "웨스테로스 북부 지방 윈터펠을 다스리는 에다드 스타크. 스타크 가문은 '겨울이 오고 있다'를 가언으로 몇 년, 때론 남은 일생 동안 계속 될지도 모르는 혹독한 겨울을 대비하며 지낸다. 그러던 중 에다드는 현재 왕좌에 있는 바라테온 가문의 로버트 왕의 핸드로서 왕을 보좌하기 위해 수도 킹스랜딩에 오게 된다. 바라테온 가문과 라니스터 가문, 왕좌를 빼앗긴 타르가옌 가문 등 칠왕국 안의 가문들은 욕망과 명예를 향한 열망으로 피 튀기는 암투를 시작하는데...", "language": "ko", "country": "ko" }, { "title": "Seizoen 1", "overview": "Het eerste seizoen van de epische fantasy tv- drama-serie Game of Thrones ging in première op HBO op 17 april 2011 en eindigde op 19 juni 2011, uitgezonden in de Verenigde Staten . Het bestaat uit 10 afleveringen , elke aflevering duurt ongeveer 55 minuten. Game of Thrones is gebaseerd op de roman A Game of Thrones , de eerste vermelding in Een Lied van IJs en Vuur serie van George RR Martin . Het verhaal speelt zich af in een fictieve wereld , in de eerste plaats op een continent genaamd Westeros . The Noble House Stark , onder leiding van Lord Eddard \" Ned \" Stark wordt betrokken in regelingen tegen koning Robert Baratheon wanneer de Hand van de Koning Jon Arryn op mysterieuze wijze sterft .", "language": "nl", "country": "nl" }, { "title": "Sesong 1", "overview": "Sesong 1 av Game of Thrones hadde premiere 17 Mai, 2011.", "language": "no", "country": "no" } ] ## Comments [/shows/{id}/seasons/{season}/comments/{sort}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `watched` + `plays` + `rating` + `added` ### Get all season comments [GET] #### 🔓 OAuth Optional 📄 Pagination 😁 Emojis Returns all top level comments for a season. 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Great season!", "spoiler": false, "review": false, "replies": 1, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Lists [/shows/{id}/seasons/{season}/lists/{type}/{sort}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + type (optional, string, `personal`) ... Filter for a specific list type + Values + `all` + `personal` + `official` + `watchlists` + sort (optional, string, `popular`) ... How to sort + Values + `popular` + `likes` + `comments` + `items` + `added` + `updated` ### Get lists containing this season [GET] #### 📄 Pagination 😁 Emojis Returns all lists that contain this season. By default, `personal` lists are returned sorted by the most `popular`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "name": "Incredible Thoughts", "description": "How could my brain conceive them?", "privacy": "public", "share_link": "https://trakt.tv/lists/1337", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 10, "likes": 99, "ids": { "trakt": 1337, "slug": "incredible-thoughts" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## People [/shows/{id}/seasons/{season}/people] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number ### Get all people for a season [GET] #### ✨ Extended Info Returns all `cast` and `crew` for a season, including the `episode_count` for which they appear. 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 at least 1 episode of the season. > ### 🅽🅾🆃🅴 > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/people ``` + Body { "cast":[ { "characters":["Daenerys Targaryen"], "episode_count":10, "person":{ "name":"Emilia Clarke", "ids":{ "trakt":2332, "slug":"emilia-clarke", "imdb":"nm3592338", "tmdb":1223786 } } }, { "characters":["Jon Snow"], "episode_count":10, "person":{ "name":"Kit Harington", "ids":{ "trakt":2333, "slug":"kit-harington", "imdb":"nm3229685", "tmdb":239019 } } }, { "characters":["Robert Baratheon"], "episode_count":10, "person":{ "name":"Mark Addy", "ids":{ "trakt":17444, "slug":"mark-addy", "imdb":"nm0004692", "tmdb":13633 } } } ], "crew":{ "production":[ { "jobs":["Executive Producer"], "episode_count":10, "person":{ "name":"David Benioff", "ids":{ "trakt":2631, "slug":"david-benioff", "imdb":"nm1125275", "tmdb":9813 } } }, { "jobs":["Co-Executive Producer"], "episode_count":10, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } } ], "sound":[ { "jobs":["Original Music Composer"], "episode_count":10, "person":{ "name":"Ramin Djawadi", "ids":{ "trakt":3698, "slug":"ramin-djawadi", "imdb":"nm1014697", "tmdb":10851 } } } ], "costume & make-up":[ { "jobs":["Costume Design"], "episode_count":10, "person":{ "name":"Michele Clapton", "ids":{ "trakt":5019, "slug":"michele-clapton", "imdb":"nm0163449", "tmdb":50953 } } } ], "writing":[ { "jobs":["Novel"], "episode_count":10, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } } ], "art":[ { "jobs":["Set Decoration"], "episode_count":10, "person":{ "name":"Richard Roberts", "ids":{ "trakt":6026, "slug":"richard-roberts", "imdb":"nm0731517", "tmdb":8410 } } }, { "jobs":["Production Design"], "episode_count":10, "person":{ "name":"Gemma Jackson", "ids":{ "trakt":17454, "slug":"gemma-jackson", "imdb":"nm0413541", "tmdb":9153 } } } ], "directing":[ { "jobs":["Director"], "episode_count":3, "person":{ "name":"Brian Kirk", "ids":{ "trakt":17511, "slug":"brian-kirk", "imdb":"nm1047532", "tmdb":93223 } } }, { "jobs":["Director"], "episode_count":3, "person":{ "name":"Daniel Minahan", "ids":{ "trakt":17514, "slug":"daniel-minahan", "imdb":"nm0590889", "tmdb":88743 } } } ] } } + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/people?extended=guest_stars ``` + Body { "cast":[ { "characters":["Daenerys Targaryen"], "episode_count":10, "person":{ "name":"Emilia Clarke", "ids":{ "trakt":2332, "slug":"emilia-clarke", "imdb":"nm3592338", "tmdb":1223786 } } }, { "characters":["Jon Snow"], "episode_count":10, "person":{ "name":"Kit Harington", "ids":{ "trakt":2333, "slug":"kit-harington", "imdb":"nm3229685", "tmdb":239019 } } }, { "characters":["Robert Baratheon"], "episode_count":10, "person":{ "name":"Mark Addy", "ids":{ "trakt":17444, "slug":"mark-addy", "imdb":"nm0004692", "tmdb":13633 } } } ], "guest_stars":[ { "characters":["Rodrik Cassel"], "episode_count":9, "person":{ "name":"Ron Donachie", "ids":{ "trakt":17471, "slug":"ron-donachie", "imdb":"nm0231871", "tmdb":63141 } } }, { "characters":["Grand Maester Pycelle"], "episode_count":8, "person":{ "name":"Julian Glover", "ids":{ "trakt":2654, "slug":"julian-glover", "imdb":"nm0002103", "tmdb":740 } } }, { "characters":["Irri"], "episode_count":8, "person":{ "name":"Amrita Acharia", "ids":{ "trakt":17478, "slug":"amrita-acharia", "imdb":"nm3822505", "tmdb":1048692 } } } ], "crew":{ "production":[ { "jobs":["Executive Producer"], "episode_count":10, "person":{ "name":"David Benioff", "ids":{ "trakt":2631, "slug":"david-benioff", "imdb":"nm1125275", "tmdb":9813 } } }, { "jobs":["Co-Executive Producer"], "episode_count":10, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } } ], "sound":[ { "jobs":["Original Music Composer"], "episode_count":10, "person":{ "name":"Ramin Djawadi", "ids":{ "trakt":3698, "slug":"ramin-djawadi", "imdb":"nm1014697", "tmdb":10851 } } } ], "costume & make-up":[ { "jobs":["Costume Design"], "episode_count":10, "person":{ "name":"Michele Clapton", "ids":{ "trakt":5019, "slug":"michele-clapton", "imdb":"nm0163449", "tmdb":50953 } } } ], "writing":[ { "jobs":["Novel"], "episode_count":10, "person":{ "name":"George R. R. Martin", "ids":{ "trakt":5020, "slug":"george-r-r-martin", "imdb":"nm0552333", "tmdb":237053 } } } ], "art":[ { "jobs":["Set Decoration"], "episode_count":10, "person":{ "name":"Richard Roberts", "ids":{ "trakt":6026, "slug":"richard-roberts", "imdb":"nm0731517", "tmdb":8410 } } }, { "jobs":["Production Design"], "episode_count":10, "person":{ "name":"Gemma Jackson", "ids":{ "trakt":17454, "slug":"gemma-jackson", "imdb":"nm0413541", "tmdb":9153 } } } ], "directing":[ { "jobs":["Director"], "episode_count":3, "person":{ "name":"Brian Kirk", "ids":{ "trakt":17511, "slug":"brian-kirk", "imdb":"nm1047532", "tmdb":93223 } } }, { "jobs":["Director"], "episode_count":3, "person":{ "name":"Daniel Minahan", "ids":{ "trakt":17514, "slug":"daniel-minahan", "imdb":"nm0590889", "tmdb":88743 } } } ] } } ## Ratings [/shows/{id}/seasons/{season}/ratings] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number ### Get season ratings [GET] Returns rating (between 0 and 10) and distribution for a season. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "rating": 9.0, "votes": 3, "distribution": { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0, "6": 0, "7": 0, "8": 0, "9": 1, "10": 2 } } ## Stats [/shows/{id}/seasons/{season}/stats] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number ### Get season stats [GET] Returns lots of season stats. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "watchers": 30521, "plays": 37986, "collectors": 12899, "collected_episodes": 87991, "comments": 115, "lists": 309, "votes": 25655 } ## Watching [/shows/{id}/seasons/{season}/watching] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number ### Get users watching right now [GET] #### ✨ Extended Info Returns all users watching this season right now. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } }, { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } ] ## Videos [/shows/{id}/seasons/{season}/videos] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number ### Get all videos [GET] #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title":"Game Of Thrones - Season 1 Recap - Official HBO UK", "url":"https://youtube.com/watch?v=e0Y8KpQpW8c", "site":"youtube", "type":"recap", "size":1080, "official":true, "published_at":"2015-05-19T16:31:23.000Z", "country":"us", "language":"en" } ] ## Report [/shows/{id}/seasons/{season}/report] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number ### Report a season [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "metadata", "message": "Season overview is wrong." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: duplicate, remove, data_refresh, metadata, adult, runtime, language, spam, tmdb, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } # Group Episodes ## Summary [/shows/{id}/seasons/{season}/episodes/{episode}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number ### Get a single episode for a show [GET] #### ✨ 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`. > ### 🅽🅾🆃🅴 > _If the `first_aired` is unknown, it will be set to `null`._ > ### 🅽🅾🆃🅴 > _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)._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/episodes/1 ``` + Body { "season": 1, "number": 1, "title": "Winter Is Coming", "ids": { "trakt": 36440, "tvdb": 3254641, "imdb": "tt1480055", "tmdb": 63056 } } + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/episodes/1?extended=full ``` + Body { "season": 1, "number": 1, "title": "Winter Is Coming", "ids": { "trakt": 36440, "tvdb": 3254641, "imdb": "tt1480055", "tmdb": 63056 }, "number_abs": null, "overview": "Ned Stark, Lord of Winterfell learns that his mentor, Jon Arryn, has died and that King Robert is on his way north to offer Ned Arryn’s position as the King’s Hand. Across the Narrow Sea in Pentos, Viserys Targaryen plans to wed his sister Daenerys to the nomadic Dothraki warrior leader, Khal Drogo to forge an alliance to take the throne.", "first_aired": "2011-04-18T01:00:00.000Z", "updated_at": "2014-08-29T23:16:39.000Z", "rating": 9.0, "votes": 111, "comment_count": 92, "available_translations": ["en"], "runtime": 58, "episode_type": "series_premiere", "original_title": "Winter Is Coming", } ## Translations [/shows/{id}/seasons/{season}/episodes/{episode}/translations/{language}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number + language (optional, string, `es`) ... 2 character language code ### Get all episode translations [GET] 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`). + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title": "Winter Is Coming", "overview": "Jon Arryn, the Hand of the King, is dead. King Robert Baratheon plans to ask his oldest friend, Eddard Stark, to take Jon's place. Across the sea, Viserys Targaryen plans to wed his sister to a nomadic warlord in exchange for an army.", "language": "en", "country": "us" }, { "title": "Se acerca el invierno", "overview": "El Lord Ned Stark está preocupado por los perturbantes reportes de un desertor del Nights Watch; El Rey Robert y los Lannisters llegan a Winterfell; el exiliado Viserys Targaryen forja una nueva y poderosa alianza.", "language": "es", "country": "es" }, { "title": "凛冬将至", "overview": "一名守夜人军团的逃兵在临冬城外被抓获，领主艾德（奈德）·史塔克下令将其处斩。奈德对绝境长城之外的形势忧心忡忡。行刑结束后，奈德回到城中，他的夫人凯特琳带来一个令人震惊的消息：奈德的良师益友、现任首相琼恩·艾林在都城离奇死亡，罗伯特国王正启程赶往北方，希望奈德接替琼恩·艾林出任国王之手。与此同时，在狭海对岸的潘托斯，韦赛里斯·坦格利安正计划与多斯拉克游牧民族的一位重要首领卓戈卡奥结盟，凭借多斯拉克人的力量夺回本属于他的铁王座。他妹妹丹妮莉斯的终身幸福成了他手中最重要的筹码。罗伯特国王带着瑟曦·兰尼斯特王后及兰尼斯特家族的重要成员抵达临冬城。他的随行人员包括：王后的弟弟詹姆和提力昂，他们一个英俊潇洒，一个却是侏儒；12岁的乔佛里王子，王位的继承人。奈德无法拒绝国王的盛情邀请，决定南下君临城帮助国王稳定国内局势。就在罗伯特和奈德动身之前，奈德的私生子琼恩·雪诺决定北上黑城堡加盟守夜人军团，对守夜人颇为好奇的提力昂打算和雪诺一同前往。厄运突然降临到奈德的次子布兰身上，奈德和琼恩都被迫推迟了行程。", "language": "zh", "country": "tw" } ] ## Comments [/shows/{id}/seasons/{season}/episodes/{episode}/comments/{sort}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `plays` + `rating` + `added` ### Get all episode comments [GET] #### 🔓 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Great episode!", "spoiler": false, "review": false, "replies": 1, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Lists [/shows/{id}/seasons/{season}/episodes/{episode}/lists/{type}/{sort}] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number + type (optional, string, `personal`) ... Filter for a specific list type + Values + `all` + `personal` + `official` + `watchlists` + sort (optional, string, `popular`) ... How to sort + Values + `popular` + `likes` + `comments` + `items` + `added` + `updated` ### Get lists containing this episode [GET] #### 📄 Pagination 😁 Emojis Returns all lists that contain this episode. By default, `personal` lists are returned sorted by the most `popular`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "name": "Incredible Thoughts", "description": "How could my brain conceive them?", "privacy": "public", "share_link": "https://trakt.tv/lists/1337", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 50, "comment_count": 10, "likes": 99, "ids": { "trakt": 1337, "slug": "incredible-thoughts" }, "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## People [/shows/{id}/seasons/{season}/episodes/{episode}/people] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number ### Get all people for an episode [GET] #### ✨ 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. > ### 🅽🅾🆃🅴 > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/episodes/1/people ``` + Body { "cast":[ { "characters":["Daenerys Targaryen"], "person":{ "name":"Emilia Clarke", "ids":{ "trakt":2332, "slug":"emilia-clarke", "imdb":"nm3592338", "tmdb":1223786 } } }, { "characters":["Jon Snow"], "person":{ "name":"Kit Harington", "ids":{ "trakt":2333, "slug":"kit-harington", "imdb":"nm3229685", "tmdb":239019 } } }, { "characters":["Robert Baratheon"], "person":{ "name":"Mark Addy", "ids":{ "trakt":17444, "slug":"mark-addy", "imdb":"nm0004692", "tmdb":13633 } } } ], "crew":{ "writing":[ { "jobs":["Writer"], "person":{ "name":"David Benioff", "ids":{ "trakt":2631, "slug":"david-benioff", "imdb":"nm1125275", "tmdb":9813 } } }, { "jobs":["Writer"], "person":{ "name":"D. B. Weiss", "ids":{ "trakt":17443, "slug":"d-b-weiss", "imdb":"nm1888967", "tmdb":228068 } } } ], "directing":[ { "jobs":["Director"], "person":{ "name":"Tim Van Patten", "ids":{ "trakt":17508, "slug":"tim-van-patten", "imdb":"nm0887700", "tmdb":44797 } } } ], "camera":[ { "jobs":["Director of Photography"], "person":{ "name":"Alik Sakharov", "ids":{ "trakt":17509, "slug":"alik-sakharov", "imdb":"nm0002399", "tmdb":1318704 } } } ], "editing":[ { "jobs":["Editor"], "person":{ "name":"Oral Norrie Ottey", "ids":{ "trakt":17510, "slug":"oral-norrie-ottey", "imdb":"nm0653205", "tmdb":18077 } } } ] } } + Response 200 (application/json) ``` /shows/game-of-thrones/seasons/1/episodes/1/people?extended=guest_stars ``` + Body { "cast":[ { "characters":["Daenerys Targaryen"], "person":{ "name":"Emilia Clarke", "ids":{ "trakt":2332, "slug":"emilia-clarke", "imdb":"nm3592338", "tmdb":1223786 } } }, { "characters":["Jon Snow"], "person":{ "name":"Kit Harington", "ids":{ "trakt":2333, "slug":"kit-harington", "imdb":"nm3229685", "tmdb":239019 } } }, { "characters":["Robert Baratheon"], "person":{ "name":"Mark Addy", "ids":{ "trakt":17444, "slug":"mark-addy", "imdb":"nm0004692", "tmdb":13633 } } } ], "guest_stars":[ { "characters":["Khal Drogo"], "person":{ "name":"Jason Momoa", "ids":{ "trakt":5038, "slug":"jason-momoa", "imdb":"nm0597388", "tmdb":117642 } } }, { "characters":["Hodor"], "person":{ "name":"Kristian Nairn", "ids":{ "trakt":13075, "slug":"kristian-nairn", "imdb":null, "tmdb":1223792 } } }, { "characters":["Benjen Stark"], "person":{ "name":"Joseph Mawle", "ids":{ "trakt":10613, "slug":"joseph-mawle", "imdb":"nm1152798", "tmdb":119783 } } } ], "crew":{ "writing":[ { "jobs":["Writer"], "person":{ "name":"David Benioff", "ids":{ "trakt":2631, "slug":"david-benioff", "imdb":"nm1125275", "tmdb":9813 } } }, { "jobs":["Writer"], "person":{ "name":"D. B. Weiss", "ids":{ "trakt":17443, "slug":"d-b-weiss", "imdb":"nm1888967", "tmdb":228068 } } } ], "directing":[ { "jobs":["Director"], "person":{ "name":"Tim Van Patten", "ids":{ "trakt":17508, "slug":"tim-van-patten", "imdb":"nm0887700", "tmdb":44797 } } } ], "camera":[ { "jobs":["Director of Photography"], "person":{ "name":"Alik Sakharov", "ids":{ "trakt":17509, "slug":"alik-sakharov", "imdb":"nm0002399", "tmdb":1318704 } } } ], "editing":[ { "jobs":["Editor"], "person":{ "name":"Oral Norrie Ottey", "ids":{ "trakt":17510, "slug":"oral-norrie-ottey", "imdb":"nm0653205", "tmdb":18077 } } } ] } } ## Ratings [/shows/{id}/seasons/{season}/episodes/{episode}/ratings] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `12`) ... episode number ### Get episode ratings [GET] Returns rating (between 0 and 10) and distribution for an episode. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "rating": 9.0, "votes": 3, "distribution": { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0, "6": 0, "7": 0, "8": 0, "9": 1, "10": 2 } } ## Stats [/shows/{id}/seasons/{season}/episodes/{episode}/stats] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number ### Get episode stats [GET] Returns lots of episode stats. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "watchers": 30521, "plays": 37986, "collectors": 12899, "collected_episodes": 87991, "comments": 115, "lists": 309, "votes": 25655 } ## Watching [/shows/{id}/seasons/{season}/episodes/{episode}/watching] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number ### Get users watching right now [GET] #### ✨ Extended Info Returns all users watching this episode right now. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } }, { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } ] ## Videos /shows/{id}/seasons/{season}/episodes/{episode}/videos] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number ### Get all videos [GET] #### ✨ Extended Info Returns all videos including trailers, teasers, clips, and featurettes. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "title":"Game of Thrones: Season 1 - Episode 2 Clip #1 (HBO)", "url":"https://youtube.com/watch?v=kPrW3Swrp4E", "site":"youtube", "type":"clip", "size":720, "official":true, "published_at":"2011-04-21T20:16:51.000Z", "country":"us", "language":"en" } ] ## Report [/shows/{id}/seasons/{season}/episodes/{episode}/report] + Parameters + id (required, string, `game-of-thrones`) ... Trakt ID, Trakt slug, or IMDB ID + season (required, integer, `1`) ... season number + episode (required, integer, `1`) ... episode number ### Report an episode [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "runtime", "message": "This episode runs 55 minutes, not 60." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: duplicate, remove, data_refresh, metadata, adult, runtime, language, spam, tmdb, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } # Group Sync Syncing with trakt opens up quite a few cool features. Most importantly, trakt can serve as a cloud based backup for the data in your app. This is especially useful when rebuilding a media center or installing a mobile app on your new phone. It can also be nice to sync up multiple media centers with a central trakt account. If everything is in sync, your media can be managed from trakt and be reflected in your apps. ### Media objects for syncing As a baseline, all *add* and *remove* sync methods accept arrays of `movies`, `shows`, and `episodes`. Each of these top level array elements should themselves be an array of standard `movie`, `show`, or `episode` objects. Full examples are in the intro section called **Standard Media Objects**. Keep in mind that `episode` objects really only need the `ids` so it can find an exact match. This is useful for absolute ordered shows. Some methods also have optional metadata you can attach, so check the docs for each specific method. Media objects will be matched by ID first, then fall back to title and year. IDs will be matched in this order `trakt`, `imdb`, `tmdb`, `tvdb`, and `slug`. If nothing is found, it will match on the `title` and `year`. If still nothing, it would use just the `title` (or `name` for people) and find the most current object that exists. ### Watched History Sync This is a 2 way sync that will get items from trakt to sync locally, plus find anything new and sync back to trakt. Perform this sync on startup or at set intervals (i.e. once every day) to keep everything in sync. *This will only send data to trakt and not remove it.* ### Collection Sync It's very handy to have a snapshot on trakt of everything you have available to watch locally. Syncing your local connection will do just that. *This will only send data to trakt and not remove it.* ### Clean Collection Cleaning a collection involves comparing the trakt collection to what exists locally. This will remove items from the trakt collection if they don't exist locally anymore. You should make this clear to the user that data might be removed from trakt. ## Last Activities [/sync/last_activities] ### Get last activity [GET] #### 🔒 OAuth Required This method is a useful first step in the syncing process. We recommended caching these dates locally, then you can compare to know exactly what data has changed recently. This can greatly optimize your syncs so you don't pull down a ton of data only to see nothing has actually changed. #### Account `settings_at` is set when the OAuth user updates any of their Trakt settings on the website. `followed_at` is set when another Trakt user follows or unfollows the OAuth user. `following_at` is set when the OAuth user follows or unfollows another Trakt user. `pending_at` is set when the OAuth user follows a private account, which requires their approval. `requested_at` is set when the OAuth user has a private account and someone requests to follow them. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "all": "2014-11-20T07:01:32.000Z", "movies": { "watched_at": "2014-11-19T21:42:41.000Z", "collected_at": "2014-11-20T06:51:30.000Z", "rated_at": "2014-11-19T18:32:29.000Z", "watchlisted_at": "2014-11-19T21:42:41.000Z", "favorited_at": "2014-11-19T21:42:41.000Z", "commented_at": "2014-11-20T06:51:30.000Z", "paused_at": "2014-11-20T06:51:30.000Z", "hidden_at": "2016-08-20T06:51:30.000Z" }, "episodes": { "watched_at": "2014-11-20T06:51:30.000Z", "collected_at": "2014-11-19T22:02:41.000Z", "rated_at": "2014-11-20T06:51:30.000Z", "watchlisted_at": "2014-11-20T06:51:30.000Z", "commented_at": "2014-11-20T06:51:30.000Z", "paused_at": "2014-11-20T06:51:30.000Z" }, "shows": { "rated_at": "2014-11-19T19:50:58.000Z", "watchlisted_at": "2014-11-20T06:51:30.000Z", "favorited_at": "2014-11-20T06:51:30.000Z", "commented_at": "2014-11-20T06:51:30.000Z", "hidden_at": "2016-08-20T06:51:30.000Z", "dropped_at": "2025-03-13T01:23:45.000Z" }, "seasons": { "rated_at": "2014-11-19T19:54:24.000Z", "watchlisted_at": "2014-11-20T06:51:30.000Z", "commented_at": "2014-11-20T06:51:30.000Z", "hidden_at": "2016-08-20T06:51:30.000Z" }, "comments": { "liked_at": "2014-11-20T03:38:09.000Z", "reacted_at": "2025-09-01T03:38:09.000Z", "blocked_at": "2022-02-22T03:38:09.000Z" }, "lists": { "liked_at": "2014-11-20T00:36:48.000Z", "reacted_at": "2025-09-01T03:38:09.000Z", "updated_at": "2014-11-20T06:52:18.000Z", "commented_at": "2014-11-20T06:51:30.000Z" }, "watchlist": { "updated_at": "2014-11-20T06:52:18.000Z" }, "favorites": { "updated_at": "2014-11-20T06:52:18.000Z" }, "account": { "settings_at": "2020-03-04T03:38:09.000Z", "followed_at": "2020-03-04T03:38:09.000Z", "following_at": "2020-03-04T03:38:09.000Z", "pending_at": "2020-03-04T03:38:09.000Z", "requested_at": "2022-04-27T03:38:09.000Z" }, "saved_filters": { "updated_at": "2022-06-14T06:52:18.000Z" }, "notes": { "updated_at": "2023-08-31T17:18:19.000Z" } } ## Playback [/sync/playback/{type}{?start_at,end_at}] + Parameters + type (optional, string, `movies`) ... + Values + `movies` + `episodes` + start_at (optional, string, `2016-06-01T00:00:00.000Z`) ... Starting date. + end_at (optional, string, `2016-07-01T23:59:59.000Z`) ... Ending date. ### Get playback progress [GET] #### 🔒 OAuth Required 📄 Pagination Optional Whenever a scrobble is paused, the playback progress is saved. Use this progress to sync up playback across different media centers or apps. For example, you can start watching a movie in a media center, stop it, then resume on your tablet from the same spot. Each item will have the `progress` percentage between 0 and 100. You can optionally specify a `type` to only get `movies` or `episodes`. By default, all results will be returned. Pagination is optional and can be used for something like an "on deck" feature, or if you only need a limited data set. > ### 🅽🅾🆃🅴 > _We only save playback progress for the last 6 months._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "progress": 10.0, "paused_at": "2015-01-25T22:01:32.000Z", "id": 13, "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } } }, { "progress": 65.5, "paused_at": "2015-01-25T22:01:32.000Z", "id": 37, "type": "episode", "episode": { "season": 0, "number": 1, "title": "Good Cop Bad Cop", "ids": { "trakt": 1, "tvdb": 3859781, "imdb": "", "tmdb": 62131 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] ## Remove Playback [/sync/playback/{id}] + Parameters + id (required, integer, `13`) ... playback ID ### Remove a playback item [DELETE] #### 🔒 OAuth Required Remove a playback item from a user's playback progress list. A `404` will be returned if the `id` is invalid. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 ## Get Collection [/sync/collection/{type}] + Parameters + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get collection [GET] #### 🔒 OAuth Required ✨ Extended Info Get all collected items in a user's collection. A collected item indicates availability to watch digitally or on physical media. Each `movie` object contains `collected_at` and `updated_at` timestamps. Since users can set custom dates when they collected movies, it is possible for `collected_at` to be in the past. We also include `updated_at` to help sync Trakt data with your app. Cache this timestamp locally and only re-process the movie if you see a newer timestamp. Each `show` object contains `last_collected_at` and `last_updated_at` timestamps. Since users can set custom dates when they collected episodes, it is possible for `last_collected_at` to be in the past. We also include `last_updated_at` to help sync Trakt data with your app. Cache this timestamp locally and only re-process the show if you see a newer timestamp. If you add `?extended=metadata` to the URL, it will return the additional `media_type`, `resolution`, `hdr`, `audio`, `audio_channels` and '3d' metadata. It will use `null` if the metadata isn't set for an item. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /sync/collection/movies ``` + Body [ { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /sync/collection/movies?extended=metadata ``` + Body [ { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } }, "metadata": { "media_type": "bluray", "resolution": "hd_1080p", "hdr": "dolby_vision", "audio": "dts", "audio_channels": "6.1", "3d": false } }, { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } }, "metadata": { "media_type": "bluray", "resolution": "hd_1080p", "hdr": "dolby_vision", "audio": "dts", "audio_channels": "6.1", "3d": false } } ] + Response 200 (application/json) ``` /sync/collection/shows ``` + Body [ { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] } ] }, { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] } ] } ] + Response 200 (application/json) ``` /sync/collection/shows?extended=metadata ``` + Body [ { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10_plus", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10_plus", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] } ] }, { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] } ] } ] ## Add to Collection [/sync/collection] ### Add items to collection [POST] #### 🔥 VIP Enhanced 🔒 🔒 OAuth Required Add items to a user's collection. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be collected. If seasons are specified, all episodes in those seasons will be collected. Send a `collected_at` UTC datetime to mark items as collected in the past. You can also send additional metadata about the media itself to have a very accurate collection. Showcase what is available to watch from your epic HD DVD collection down to your downloaded iTunes movies. #### Limits If the user's collection 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. > ### 🅽🅾🆃🅴 > _You can resend items already in your collection and they will be updated with any new values. This includes the `collected_at` and any other metadata._ #### 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. | | `collected_at` | datetime | UTC datetime when the item was collected. Set to `released` to automatically use the inital release date + runtime *(episodes only)*). | | `media_type` | string | Set to `digital`, `bluray`, `hddvd`, `dvd`, `vcd`, `vhs`, `betamax`, or `laserdisc`. | | `resolution` | string | Set to `uhd_4k`, `hd_1080p`, `hd_1080i`, `hd_720p`, `sd_480p`, `sd_480i`, `sd_576p`, or `sd_576i`. | | `hdr` | string | Set to `dolby_vision`, `hdr10`, `hdr10_plus`, or `hlg`. | | `audio` | string | Set to `dolby_digital`, `dolby_digital_plus`, `dolby_digital_plus_atmos`, `dolby_truehd`, `dolby_atmos` *(Dolby TrueHD Atmos)*, `dolby_prologic`, `dts`, `dts_ma`, `dts_hr`, `dts_x`, `auro_3d`, `mp3`, `mp2`, `aac`, `lpcm`, `ogg` *(Ogg Vorbis)*, `ogg_opus`, `wma`, or `flac`. | | `audio_channels` | string | Set to `1.0`, `2.0`, `2.1`, `3.0`, `3.1`, `4.0`, `4.1`, `5.0`, `5.1`, `5.1.2`, `5.1.4`, `6.1`, `7.1`, `7.1.2`, `7.1.4`, `9.1`, or `10.1` | | `3d` | boolean | Set `true` if in 3D. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "collected_at": "2014-09-01T09:10:11.000Z", "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 }, "media_type": "digital", "resolution": "uhd_4k", "hdr": "dolby_vision", "audio": "dts_ma", "audio_channels": "5.1" }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "media_type": "bluray", "resolution": "hd_1080p", "audio": "dolby_digital_plus", "audio_channels": "5.1" }, { "number": 2 } ] } ] } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ] } + Response 201 (application/json) + Body { "added": { "movies": 1, "episodes": 12 }, "updated": { "movies": 0, "episodes": 0 }, "existing": { "movies": 0, "episodes": 0 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [] } } ## Remove from Collection [/sync/collection/remove] ### Remove items from collection [POST] #### 🔒 OAuth Required Remove one or more items from a user's collection. #### 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "number": 1 }, { "number": 2 } ] } ] } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ] } + Response 200 (application/json) + Body { "deleted": { "movies": 1, "episodes": 12 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [] } } ## Get Watched [/sync/watched/{type}] + Parameters + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get watched [GET] #### 🔒 OAuth Required ✨ Extended Info Returns all movies or shows a user has watched sorted by most recently watched. If `type` is set to _shows_ and you add `?extended=noseasons` to the URL, it won't return season or episode info. Each `movie` and `show` object contains `last_watched_at` and `last_updated_at` timestamps. Since users can set custom dates when they watched movies and episodes, it is possible for `last_watched_at` to be in the past. We also include `last_updated_at` to help sync Trakt data with your app. Cache this timestamp locally and only re-process the movies and shows if you see a newer timestamp. Each `show` object contains a `reset_at` timestamp. If not `null`, this 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`. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /sync/watched/movies ``` + Body [ { "plays": 4, "last_watched_at": "2014-10-11T17:00:54.000Z", "last_updated_at": "2014-10-11T17:00:54.000Z", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 6, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } } }, { "plays": 2, "last_watched_at": "2014-10-12T17:00:54.000Z", "last_updated_at": "2014-10-12T17:00:54.000Z", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /sync/watched/shows ``` + Body [ { "plays": 56, "last_watched_at": "2014-10-11T17:00:54.000Z", "last_updated_at": "2014-10-11T17:00:54.000Z", "reset_at": null, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] } ] }, { "plays": 23, "last_watched_at": "2014-10-12T17:00:54.000Z", "last_updated_at": "2014-10-12T17:00:54.000Z", "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] } ] } ] + Response 200 (application/json) ``` /sync/watched/shows?extended=noseasons ``` + Body [ { "plays": 56, "last_watched_at": "2014-10-11T17:00:54.000Z", "last_updated_at": "2014-10-11T17:00:54.000Z", "reset_at": null, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "plays": 23, "last_watched_at": "2014-10-12T17:00:54.000Z", "last_updated_at": "2014-10-12T17:00:54.000Z", "reset_at": "2019-08-12T17:00:54.000Z", "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } } ] ## Get History [/sync/history/{type}/{id}{?start_at,end_at}] + Parameters + type (optional, string, `movies`) ... + Values + `movies` + `shows` + `seasons` + `episodes` + id (optional, integer, `123`) ... Trakt ID for a specific item. + start_at (optional, string, `2016-06-01T00:00:00.000Z`) ... Starting date. + end_at (optional, string, `2016-07-01T23:59:59.000Z`) ... Ending date. ### Get watched history [GET] #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Returns movies and episodes that a user has watched, sorted by most recent. You can optionally limit the `type` to `movies` or `episodes`. The `id` _(64-bit integer)_ in each history item uniquely identifies the event and can be used to remove individual events by using the [**/sync/history/remove**](#reference/sync/remove-from-history/get-watched-history) method. The `action` will be set to `scrobble`, `checkin`, or `watch`. Specify a `type` and trakt `id` to limit the history for just that item. If the `id` is valid, but there is no history, an empty array will be returned. | Example URL | Returns watches for... | |---|---| | `/history/movies/12601` | TRON: Legacy | | `/history/shows/1388` | All episodes of Breaking Bad | | `/history/seasons/3950` | All episodes of Breaking Bad: Season 1 | | `/history/episodes/73482` | Only episode 1 of Breaking Bad: Season 1 | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /sync/history ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 1982346, "watched_at": "2014-03-31T09:28:53.000Z", "action": "scrobble", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "id": 1982347, "watched_at": "2014-02-27T09:28:53.000Z", "action": "checkin", "type": "episode", "episode": { "season": 2, "number": 1, "title": "Pawnee Zoo", "ids": { "trakt": 251, "tvdb": 797571, "imdb": null, "tmdb": 397629 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } }, { "id": 1982348, "watched_at": "2013-06-15T05:54:27.000Z", "action": "watch", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } } ] + Response 200 (application/json) ``` /sync/history/movies ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 1982346, "watched_at": "2014-03-31T09:28:53.000Z", "action": "scrobble", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "id": 1982347, "watched_at": "2013-12-07T09:04:59.000Z", "action": "checkin", "type": "movie", "movie": { "title": "Thor: The Dark World", "year": 2013, "ids": { "trakt": 10, "slug": "thor-the-dark-world-2013", "imdb": "tt1981115", "tmdb": 76338 } } }, { "id": 1982348, "watched_at": "2013-06-15T05:54:27.000Z", "action": "watch", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } } ] + Response 200 (application/json) ``` /sync/history/episodes ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 1982346, "watched_at": "2014-03-31T09:28:53.000Z", "action": "scrobble", "type": "episode", "episode": { "season": 2, "number": 1, "title": "Pawnee Zoo", "ids": { "trakt": 251, "tvdb": 797571, "imdb": null, "tmdb": 397629 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } }, { "id": 1982347, "watched_at": "2014-03-31T09:28:53.000Z", "action": "checkin", "type": "episode", "episode": { "season": 2, "number": 2, "title": "The Stakeout", "ids": { "trakt": 252, "tvdb": 1088031, "imdb": null, "tmdb": 397627 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } }, { "id": 1982348, "watched_at": "2014-03-31T09:28:53.000Z", "action": "watch", "type": "episode", "episode": { "season": 2, "number": 3, "title": "Beauty Pageant", "ids": { "trakt": 253, "tvdb": 1088041, "imdb": null, "tmdb": 397642 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } } ] ## Add to History [/sync/history] ### Add items to watched history [POST] #### 🔒 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. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > _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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "watched_at": "2014-09-01T09:10:11.000Z", "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "watched_at": "2014-09-01T09:10:11.000Z", "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "watched_at": "2014-09-01T09:10:11.000Z", "number": 1 }, { "number": 2 } ] } ] } ], "seasons": [ { "watched_at": "2019-01-02T09:10:11.000Z", "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "watched_at": "2014-09-01T09:10:11.000Z", "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ] } + Response 201 (application/json) + Body { "added": { "movies": 2, "episodes": 72 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [] } } ## Remove from History [/sync/history/remove] ### Remove items from history [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "number": 1 }, { "number": 2 } ] } ] } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ], "ids": [ 4, 8, 15, 16, 23, 42 ] } + Response 200 (application/json) + Body { "deleted": { "movies": 2, "episodes": 72 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [], "ids": [23, 42] } } ## Get Ratings [/sync/ratings/{type}/{rating}] + Parameters + type (optional, string, `movies`) ... + Values + `movies` + `shows` + `seasons` + `episodes` + `all` + rating (optional, integer, `9`) ... Filter for a specific rating. + Values + `1` + `2` + `3` + `4` + `5` + `6` + `7` + `8` + `9` + `10` ### Get ratings [GET] #### 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info Get a user's ratings filtered by `type`. You can optionally filter for a specific `rating` between 1 and 10. Send a comma separated string for `rating` if you need multiple ratings. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /sync/ratings/movies ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /sync/ratings/shows ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] + Response 200 (application/json) ``` /sync/ratings/seasons ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 8, "type": "season", "season": { "number": 0, "ids": { "tvdb": 439371, "tmdb": 3577 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 9, "type": "season", "season": { "number": 1, "ids": { "tvdb": 30272, "tmdb": 3572 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] + Response 200 (application/json) ``` /sync/ratings/episodes ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "episode", "episode": { "season": 4, "number": 1, "title": "Box Cutter", "ids": { "trakt": 49, "tvdb": 2639411, "imdb": "tt1683084", "tmdb": 62118 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "episode", "episode": { "season": 4, "number": 8, "title": "Hermanos", "ids": { "trakt": 56, "tvdb": 4127161, "imdb": "tt1683095", "tmdb": 62127 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] ## Add Ratings [/sync/ratings] ### Add new ratings [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 5, "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "rating": 10, "ids": { "imdb": "tt0000111" } } ], "shows": [ { "rating": 10, "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "rating": 9, "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "rating": 8, "number": 1 }, { "rating": 8, "number": 2 } ] } ] } ], "seasons": [ { "rating": 10, "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "rating": 7, "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ] } + Response 201 (application/json) + Body { "added": { "movies": 1, "shows": 1, "seasons": 1, "episodes": 2 }, "not_found": { "movies": [ { "rating": 10, "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [] } } ## Remove Ratings [/sync/ratings/remove] ### Remove ratings [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "number": 1 }, { "number": 2 } ] } ] } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ] } + Response 200 (application/json) + Body { "deleted": { "movies": 1, "shows": 1, "seasons": 1, "episodes": 2 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [] } } ## Get Watchlist [/sync/watchlist/{type}/{sort_by}/{sort_how}] + Parameters + type (optional, string, `all`) ... Filter for a specific item type + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + sort_by (optional, string, `rank`) ... Sort by a specific property + Values + `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 (optional, string, `asc`) ... Sort direction + Values + `asc` + `desc` ### Get watchlist [GET] #### 🔥 **VIP Enhanced** 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis Returns all items in a user's watchlist filtered by type. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > The watchlist should not be used as a list of what the user is actively watching. Use a combination of the [**/sync/watched**](/reference/sync/get-watched) and [**/shows/:id/progress**](/reference/shows/watched-progress) methods to get what the user is actively watching. #### Notes Each watchlist item contains a `notes` field with text entered by the user. #### Sorting Default sorting is based on the list defaults and sent in the `X-Sort-By` and `X-Sort-How` headers. If you specify the `sort_by` and `sort_how` parameters, the response will be sorted based on those values and sent in the `X-Applied-Sort-By` and `X-Applied-Sort-How` headers. Some `sort_by` options are 🔥 **VIP Only** including `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, and `tmdb_votes`. If sent for a non VIP, the items will fall back to `rank`. #### Auto Removal When an item is watched, it will be automatically removed from the watchlist. For shows and seasons, watching 1 episode will remove the entire show or season. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /sync/watchlist/movies ``` + Headers X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Need to catch up before TRON 3 is out.", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Really need to check out Heath Ledger's performance in this.", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /sync/watchlist/shows ``` + Headers X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "How have I not watched this yet?", "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] + Response 200 (application/json) ``` /sync/watchlist/seasons ``` + Headers X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "season", "season": { "number": 3, "ids": { "tvdb": 171641, "tmdb": 3575 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "season", "season": { "number": 1, "ids": { "tvdb": 30272, "tmdb": 3572 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] + Response 200 (application/json) ``` /sync/watchlist/episodes ``` + Headers X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "episode", "episode": { "season": 4, "number": 1, "title": "Box Cutter", "ids": { "trakt": 49, "tvdb": 2639411, "imdb": "tt1683084", "tmdb": 62118 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "episode", "episode": { "season": 4, "number": 8, "title": "Hermanos", "ids": { "trakt": 56, "tvdb": 4127161, "imdb": "tt1683095", "tmdb": 62127 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] ## Update Watchlist [/sync/watchlist] ### Update watchlist [PUT] #### 🔒 OAuth Required Update the watchlist by sending 1 or more parameters. #### JSON POST Data | Key | Type | Value | |---|---|---|---| | `description` | string | Description for the watchlist. | | `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` | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "description": "This is my watchlist!", "sort_by": "runtime", "sort_how": "desc" } + Response 200 (application/json) + Body { "name": "Watchlist", "description": "This is my watchlist!", "privacy": "public", "share_link": "https://trakt.tv/lists/1", "type": "watchlist", "display_numbers": false, "allow_comments": false, "sort_by": "runtime", "sort_how": "desc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2023-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 1, "slug": null }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ## Add to Watchlist [/sync/watchlist] ### Add items to watchlist [POST] #### 🔥 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 }, "notes": "One of Chritian Bale's most iconic roles." }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 }, "notes": "I AM THE DANGER!" }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "number": 1 }, { "number": 2 } ] } ] } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ] } + Response 201 (application/json) + Body { "added": { "movies": 1, "shows": 1, "seasons": 1, "episodes": 2 }, "existing": { "movies": 0, "shows": 0, "seasons": 0, "episodes": 0 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [] }, "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 5 } } + Response 420 (application/json) + Headers X-Upgrade-URL: https://trakt.tv/vip X-VIP-User: false X-Account-Limit: 250 ## Remove from Watchlist [/sync/watchlist/remove] ### Remove items from watchlist [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] }, { "title": "Mad Men", "year": 2007, "ids": { "trakt": 4, "slug": "mad-men", "tvdb": 80337, "imdb": "tt0804503", "tmdb": 1104 }, "seasons": [ { "number": 1, "episodes": [ { "number": 1 }, { "number": 2 } ] } ] } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ] } + Response 200 (application/json) + Body { "deleted": { "movies": 1, "shows": 1, "seasons": 1, "episodes": 2 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [] }, "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 0 } } ## Reorder Watchlist [/sync/watchlist/reorder] ### Reorder watchlist items [POST] #### 🔒 OAuth Required Reorder all items on a user's watchlist by sending the updated `rank` of list item ids. Use the [**/sync/watchlist**](#reference/sync/get-watchlist) method to get all list item ids. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "rank": [ 923, 324, 98768, 456456, 345, 12, 990 ] } + Response 200 (application/json) + Body { "updated": 6, "skipped_ids": [12], "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 5 } } ## Update Watchlist Item [/sync/watchlist/{list_item_id}] + Parameters + list_item_id (required, integer, `1337`) ... List Item ID ### Update a watchlist item [PUT] #### 🔥 VIP Enhanced 🔒 OAuth Required 😁 Emojis Update the `notes` on a single watchlist item. #### Limits If the user's note 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. Upgrading to [**Trakt VIP**](https://trakt.tv/vip) allows for unlimited notes + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "notes": "This is a great movie!" } + Response 204 (application/json) ## Get Favorites [/sync/favorites/{type}/{sort_by}/{sort_how}] + Parameters + type (optional, string, `all`) ... Filter for a specific item type + Values + `all` + `movies` + `shows` + sort_by (optional, string, `rank`) ... Sort by a specific property + Values + `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 (optional, string, `asc`) ... Sort direction + Values + `asc` + `desc` ### Get favorites [GET] #### 🔥 **VIP Enhanced** 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis If the user only had 100 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 contains a `notes` field explaining why the user favorited the item. #### Sorting Default sorting is based on the list defaults and sent in the `X-Sort-By` and `X-Sort-How` headers. If you specify the `sort_by` and `sort_how` parameters, the response will be sorted based on those values and sent in the `X-Applied-Sort-By` and `X-Applied-Sort-How` headers. Some `sort_by` options are 🔥 **VIP Only** including `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, and `tmdb_votes`. If sent for a non VIP, the items will fall back to `rank`. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /sync/favorites/movies ``` + Headers X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Daft Punk really knocks it out of the park on the soundtrack.", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Heath Ledger's Joker transformation is truly epic.", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /sync/favorites/shows ``` + Headers X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "I AM THE DANGER!", "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Atmospheric for days.", "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## Update Favorites [/sync/favorites] ### Update favorites [PUT] #### 🔒 OAuth Required Update the favorites list by sending 1 or more parameters. #### JSON POST Data | Key | Type | Value | |---|---|---|---| | `description` | string | Description for the favorites list. | | `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` | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "description": "These are my favorites!", "sort_by": "runtime", "sort_how": "desc" } + Response 200 (application/json) + Body { "name": "Favorites", "description": "These are my favorites!", "privacy": "public", "share_link": "https://trakt.tv/lists/2", "type": "favorites", "display_numbers": false, "allow_comments": false, "sort_by": "runtime", "sort_how": "desc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2023-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 2, "slug": null }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ## Add to Favorites [/sync/favorites] ### Add items to favorites [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 }, "notes": "One of Chritian Bale's most iconic roles." }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 }, "notes": "I AM THE DANGER!" }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } ] } + Response 201 (application/json) + Body { "added": { "movies": 1, "shows": 2 }, "existing": { "movies": 0, "shows": 0 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [] }, "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 3 } } ## Remove from Favorites [/sync/favorites/remove] ### Remove items from favorites [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } ] } + Response 200 (application/json) + Body { "deleted": { "movies": 1, "shows": 1 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [] }, "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 0 } } ## Reorder Favorites [/sync/favorites/reorder] ### Reorder favorited items [POST] #### 🔒 OAuth Required Reorder all items on a user's favorites by sending the updated `rank` of list item ids. Use the [**/sync/favorites**](#reference/sync/get-favorites) method to get all list item ids. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "rank": [ 923, 324, 98768, 456456, 345, 12, 990 ] } + Response 200 (application/json) + Body { "updated": 6, "skipped_ids": [12], "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 3 } } ## Update Favorite Item [/sync/favorites/{list_item_id}] + Parameters + list_item_id (required, integer, `1337`) ... List Item ID ### Update a favorite item [PUT] #### 🔒 OAuth Required 😁 Emojis Update the `notes` on a single favorite item. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "notes": "This is a great movie!" } + Response 204 (application/json) # Group Users User's with public data will return info with all GET methods. Private user's (including yourself) require valid OAuth and a friend relationship to return data. ### Username vs. Slug All `users` methods should use the `slug` to identify the user. The `slug` is a URL safe and globally unique version of the `username`. ### Special ID for the OAuth user If you send valid OAuth, you can use `me` to identify the OAuth user instead of needing their actual slug. You can of course still use their actual slug, it's up to you. ### Extra Headers If valid OAuth is sent, additional headers will be sent to better determine it is a data permissions issue (they aren't friends) and not bad OAuth. For example, you might try and access a private user's list you aren't friends with. This will return a `401` HTTP status code and the additional headers. This means the OAuth is valid, but authorization ultimately failed because there is no friend relationship. | Header | Value | |---|---| | `X-Private-User` | `true` or `false` | ### Creating New Users Since the API uses OAuth, users can create a new account during that flow if they need to. As far as your app is concerned, you'll still receive OAuth tokens no matter if they sign in with an existing account or create a new one. ## Settings [/users/settings] ### Retrieve settings [GET] #### 🔒 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin", "uuid": "b6589fc6ab0dc82cf12099d1c2d40ab994e8410c" }, "joined_at": "2010-09-25T17:49:25.000Z", "location": "San Diego, CA", "about": "Co-founder of trakt.", "gender": "male", "age": 32, "images": { "avatar": { "full": "https://secure.gravatar.com/avatar/30c2f0dfbc39e48656f40498aa871e33?r=pg\u0026s=256" } }, "vip_og": true, "vip_years": 5 }, "account": { "timezone": "America/Los_Angeles", "date_format": "mdy", "time_24hr": false, "cover_image": "https://walter-r2.trakt.tv/images/movies/000/001/545/fanarts/original/0abb604492.jpg" }, "connections": { "facebook": false, "twitter": true, "mastodon": true, "google": true, "tumblr": false, "medium": false, "slack": false, "apple": false, "dropbox": false, "microsoft": false }, "sharing_text": { "watching": "I'm watching [item]", "watched": "I just watched [item]", "rated": "[item] [stars]" }, "limits": { "list": { "count": 2, "item_count": 100 }, "watchlist": { "item_count": 100 }, "favorites": { "item_count": 100 }, "search": { "recent_count": 5 }, "collection": { "item_count": 100 }, "notes": { "item_count": 100 } }, "permissions": { "commenting": true, "liking": true, "following": true } } ## Following Requests [/users/requests/following] ### Get pending following requests [GET] #### 🔒 OAuth Required ✨ Extended Info List a user's pending following requests that they're waiting for the other user's to approve. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "id": 3, "requested_at": "2014-09-22T04:23:48.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Follower Requests [/users/requests] ### Get follow requests [GET] #### 🔒 OAuth Required ✨ Extended Info List a user's pending follow requests so they can either approve or deny them. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "id": 3, "requested_at": "2014-09-22T04:23:48.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Approve or Deny Follower Requests [/users/requests/{id}] + Parameters + id (required, integer, `123`) ... ID of the follower request. ### Approve follow request [POST] #### 🔒 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "followed_at": "2014-09-22T05:38:54.083Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ### Deny follow request [DELETE] #### 🔒 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ## Saved Filters [/users/saved_filters/{section}] + Parameters + section (optional, string, `movies`) ... + Values + `movies` + `shows` + `calendars` + `search` ### Get saved filters [GET] #### 🔥 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 2 + Body [ { "rank": 1, "id": 101, "section": "movies", "name": "Movies: IMDB + TMDB ratings", "path": "/movies/favorited/weekly", "query": "imdb_ratings=6.9-10.0&tmdb_ratings=4.2-10.0", "updated_at": "2022-06-15T11:15:06.000Z" }, { "rank": 2, "id": 102, "section": "shows", "name": "Shows: US + Disney+", "path": "/shows/popular", "query": "watchnow=disney_plus&countries=us", "updated_at": "2022-06-15T12:15:06.000Z" }, { "rank": 3, "id": 103, "section": "calendars", "name": "On Netflix", "path": "/calendars/my/shows", "query": "network_ids=53", "updated_at": "2022-06-15T13:15:06.000Z" }, { "rank": 4, "id": 104, "section": "search", "name": "Action & Adventure", "path": "/search/movie,show", "query": "genres=+action,+adventure", "updated_at": "2022-06-15T14:15:06.000Z" } ] ## Hidden Items [/users/hidden/{section}{?type}] + Parameters + section (required, string, `calendar`) ... + Values + `calendar` + `progress_watched` + `progress_watched_reset` + `progress_collected` + `recommendations` + `comments` + `dropped` + type (optional, string, ``) ... Narrow down by element type. + Values + `movie` + `show` + `season` + `user` ### Get hidden items [GET] #### 🔒 OAuth Required 📄 Pagination ✨ Extended Info Get hidden items for a section. This will return an array of standard media objects. You can optionally limit the `type` of results to return. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 2 + Body [ { "hidden_at": "2015-03-30T23:18:42.000Z", "type": "show", "show": { "title": "Gossip Girl", "year": 2007, "ids": { "trakt": 48, "slug": "gossip-girl", "tvdb": 80547, "imdb": "tt0397442", "tmdb": 1395 } } }, { "hidden_at": "2015-03-30T23:19:33.000Z", "type": "show", "show": { "title": "Bitten", "year": 2014, "ids": { "trakt": 839, "slug": "bitten", "tvdb": 269550, "imdb": "tt2365946", "tmdb": 60556 } } } ] ## Add Hidden Items [/users/hidden/{section}] + Parameters + section (required, string, `calendar`) ... + Values + `calendar` + `progress_watched` + `progress_collected` + `recommendations` + `dropped` ### Add hidden items [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "hidden_at": "2015-03-30T23:18:42.000Z", "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] } ], "seasons": [ { "ids": { "trakt": 1337 } } ] } + Response 201 (application/json) + Body { "added": { "movies": 1, "shows": 2, "seasons": 2, "users": 0 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "users": [] } } ## Remove Hidden Items [/users/hidden/{section}/remove] + Parameters + section (required, string, `calendar`) ... + Values + `calendar` + `progress_watched` + `progress_collected` + `recommendations` + `comments` + `dropped` ### Remove hidden items [POST] #### 🔒 OAuth Required Unhide items for a specific section. Here's what type of items can unhidden for each section. #### Unhideable 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 }, "seasons": [ { "number": 3 } ] } ], "seasons": [ { "ids": { "trakt": 1337 } } ] } + Response 200 (application/json) + Body { "deleted": { "movies": 1, "shows": 2, "seasons": 2, "users": 0 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "users": [] } } ## Profile [/users/{id}] + Parameters + id (required, string, `sean`) ... User slug ### Get user profile [GET] #### 🔓 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) Public user or approved follower. + Body { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": true, "ids": { "slug": "sean" } } + Response 200 (application/json) Private user. + Body { "username": "sean", "private": true, "ids": { "slug": "sean" } } + Response 200 (application/json) ``` /users/sean?extended=full ``` + Body { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": true, "ids": { "slug": "sean" }, "joined_at": "2010-09-25T17:49:25.000Z", "location": "SF", "about": "I have all your cassette tapes.", "gender": "male", "age": 35, "images": { "avatar": { "full": "https://walter-dev.trakt.tv/images/users/000/000/001/avatars/large/0ba3f72910.jpg" } } } + Response 200 (application/json) ``` /users/sean?extended=vip ``` + Body { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": true, "ids": { "slug": "sean" }, "vip_og": true, "vip_years": 5, "vip_cover_image": "https://walter-r2.trakt.tv/images/movies/000/000/343/fanarts/full/5aab754f58.jpg" } ## Likes [/users/{id}/likes/{type}] + Parameters + id (required, string, `sean`) ... User slug + type (optional, string, ``) ... + Values + `comments` + `lists` ### Get likes [GET] #### 🔒 OAuth Optional 📄 Pagination Get items a user likes. This will return an array of standard media objects. You can optionally limit the `type` of results to return. #### Comment Media Objects If you add `?extended=comments` to the URL, it will return media objects for each comment like. > ### 🅽🅾🆃🅴 > _This returns a lot of data, so please only use this extended parameter if you actually need it!_ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/likes/comments ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 2 + Body [ { "liked_at": "2015-03-30T23:18:42.000Z", "type": "comment", "comment": { "id": 190, "parent_id": 0, "created_at": "2014-08-04T06:46:01.000Z", "updated_at": "2014-08-04T06:46:01.000Z", "comment": "Oh, I wasn't really listening.", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } } ] + Response 200 (application/json) ``` /users/sean/likes/comments?extended=comments ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 2 + Body [ { "liked_at": "2015-03-30T23:18:42.000Z", "type": "comment", "comment": { "id": 190, "parent_id": 0, "created_at": "2014-08-04T06:46:01.000Z", "updated_at": "2014-08-04T06:46:01.000Z", "comment": "Oh, I wasn't really listening.", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, "comment_type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } } } ] + Response 200 (application/json) ``` /users/sean/likes/lists ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 2 + Body [ { "liked_at": "2015-03-31T23:18:42.000Z", "type": "list", "list": { "name": "Star Wars in NEW machete order", "description": "Next time you want to introduce someone to Star Wars for the first time, watch the films with them in this order: IV, V, II, III, VI.", "privacy": "private", "share_link": "https://trakt.tv/lists/55", "display_numbers": true, "allow_comments": false, "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 55, "slug": "star-wars-in-machete-order" }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } } ] ## Collection [/users/{id}/collection/{type}] + Parameters + id (required, string, `sean`) ... User slug + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get collection [GET] #### 🔓 OAuth Optional ✨ Extended Info Get all collected items in a user's collection. A collected item indicates availability to watch digitally or on physical media. Each `movie` object contains `collected_at` and `updated_at` timestamps. Since users can set custom dates when they collected movies, it is possible for `collected_at` to be in the past. We also include `updated_at` to help sync Trakt data with your app. Cache this timestamp locally and only re-process the movie if you see a newer timestamp. Each `show` object contains `last_collected_at` and `last_updated_at` timestamps. Since users can set custom dates when they collected episodes, it is possible for `last_collected_at` to be in the past. We also include `last_updated_at` to help sync Trakt data with your app. Cache this timestamp locally and only re-process the show if you see a newer timestamp. If you add `?extended=metadata` to the URL, it will return the additional `media_type`, `resolution`, `hdr`, `audio`, `audio_channels` and '3d' metadata. It will use `null` if the metadata isn't set for an item. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/collection/movies ``` + Body [ { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /users/sean/collection/movies?extended=metadata ``` + Body [ { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } }, "metadata": { "media_type": "bluray", "resolution": "hd_1080p", "hdr": "dolby_vision", "audio": "dts", "audio_channels": "6.1", "3d": false } }, { "collected_at": "2014-09-01T09:10:11.000Z", "updated_at": "2014-09-01T09:10:11.000Z", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } }, "metadata": { "media_type": "bluray", "resolution": "hd_1080p", "hdr": "dolby_vision", "audio": "dts", "audio_channels": "6.1", "3d": false } } ] + Response 200 (application/json) ``` /users/sean/collection/shows ``` + Body [ { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] } ] }, { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z" }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z" } ] } ] } ] + Response 200 (application/json) ``` /users/sean/collection/shows?extended=metadata ``` + Body [ { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10_plus", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10_plus", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] } ] }, { "last_collected_at": "2014-09-01T09:10:11.000Z", "last_updated_at": "2014-09-01T09:10:11.000Z", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] }, { "number": 2, "episodes": [ { "number": 1, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } }, { "number": 2, "collected_at": "2014-09-01T09:10:11.000Z", "metadata": { "media_type": "digital", "resolution": "hd_720p", "hdr": "hdr10", "audio": "aac", "audio_channels": "5.1", "3d": false } } ] } ] } ] ## Comments [/users/{id}/comments/{comment_type}/{type}{?include_replies}] + Parameters + id (required, string, `sean`) ... User slug + comment_type (optional, string, `all`) ... + Values + `all` + `reviews` + `shouts` + type (optional, string, `all`) ... + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + `lists` + include_replies (optional, string, `false`) ... include comment replies + Values + `true` + `false` + `only` ### Get comments [GET] #### 🔓 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/comments ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "comment": { "id": 267, "comment": "Great kickoff to a new Batman trilogy!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-25T00:14:57.000Z", "updated_at": "2015-04-25T00:14:57.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "comment": { "id": 199, "comment": "Skyler, I AM THE DANGER.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-02-18T06:02:30.000Z", "updated_at": "2015-02-18T06:02:30.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 10, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "season", "season": { "number": 1, "ids": { "trakt": 3958, "tvdb": 274431, "tmdb": 60394 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 220, "comment": "Kicking off season 1 for a new Batman show.", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T06:53:25.000Z", "updated_at": "2015-04-21T06:53:25.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": 8, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "episode", "episode": { "season": 1, "number": 1, "title": "Jim Gordon", "ids": { "trakt": 63958, "tvdb": 4768720, "imdb": "tt3216414", "tmdb": 975968 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "comment": { "id": 229, "comment": "Is this the OC?", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2015-04-21T15:42:31.000Z", "updated_at": "2015-04-21T15:42:31.000Z", "replies": 1, "likes": 0, "user_stats": { "rating": 7, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } }, { "type": "list", "list": { "name": "Star Wars", "description": "The complete Star Wars saga!", "privacy": "public", "share_link": "https://trakt.tv/lists/51", "display_numbers": false, "allow_comments": true, "updated_at": "2015-04-22T22:01:39.000Z", "item_count": 8, "comment_count": 0, "likes": 0, "ids": { "trakt": 51, "slug": "star-wars" } }, "comment": { "id": 268, "comment": "May the 4th be with you!", "spoiler": false, "review": false, "parent_id": 0, "created_at": "2014-12-08T17:34:51.000Z", "updated_at": "2014-12-08T17:34:51.000Z", "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "justin", "private": false, "name": "Justin N.", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } } ] ## Notes [/users/{id}/notes/{type}] + Parameters + id (required, string, `sean`) ... User slug + type (optional, string, `all`) ... + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + `people` + `history` + `collection` + `ratings` ### Get notes [GET] #### 🔥 VIP Enhanced 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns the most recently notes for the user. You can optionally filter by media `type` to limit what gets returned. Use the `attached_to` info to know what the note is actually added to. Media items like `movie`, `show`, `season`, `episode`, or `person` are straightforward, but `history` will need to be mapped to that specific play in their watched history since they might have multiple plays. Since `collection` and `rating` is a 1:1 association, you can assume the note is attached to the media item in the `type` field that has been collected or rated. #### Limits Standard accounts are allowed a limited amount of notes, upgrading to [**Trakt VIP**](https://trakt.tv/vip) allows unlimited notes. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/notes ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "attached_to": { "type": "movie" }, "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "note":{ "id":49, "notes":"Only watch the extended edition.", "privacy":"private", "spoiler":false, "created_at":"2023-09-07T20:10:18.000Z", "updated_at":"2023-09-07T20:10:56.000Z", "user":{ "username":"justin", "private":false, "name":"Justin Nemeth", "vip":true, "vip_ep":true, "ids":{ "slug":"justin", "trakt":1 } } } }, { "attached_to": { "type": "episode" }, "type": "episode", "episode": { "season": 1, "number": 1, "title": "Jim Gordon", "ids": { "trakt": 63958, "tvdb": 4768720, "imdb": "tt3216414", "tmdb": 975968 } }, "show": { "title": "Gotham", "year": 2014, "ids": { "trakt": 869, "slug": "gotham", "tvdb": 274431, "imdb": "tt3749900", "tmdb": 60708 } }, "note":{ "id":48, "notes":"Streaming quality on Netflix is mediocre.", "privacy":"private", "spoiler":false, "created_at":"2023-09-07T20:03:26.000Z", "updated_at":"2023-09-07T20:03:26.000Z", "user":{ "username":"justin", "private":false, "name":"Justin Nemeth", "vip":true, "vip_ep":true, "ids":{ "slug":"justin", "trakt":1 } } } } ] + Response 200 (application/json) ``` /users/sean/notes/history ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "attached_to": { "type": "history", "id": 3253454 }, "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "note":{ "id":49, "notes":"Only watch the extended edition.", "privacy":"private", "spoiler":false, "created_at":"2023-09-07T20:10:18.000Z", "updated_at":"2023-09-07T20:10:56.000Z", "user":{ "username":"justin", "private":false, "name":"Justin Nemeth", "vip":true, "vip_ep":true, "ids":{ "slug":"justin", "trakt":1 } } } } ] + Response 200 (application/json) ``` /users/sean/notes/collection ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "attached_to": { "type": "collection" }, "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "note":{ "id":49, "notes":"Only watch the extended edition.", "privacy":"private", "spoiler":false, "created_at":"2023-09-07T20:10:18.000Z", "updated_at":"2023-09-07T20:10:56.000Z", "user":{ "username":"justin", "private":false, "name":"Justin Nemeth", "vip":true, "vip_ep":true, "ids":{ "slug":"justin", "trakt":1 } } } } ] + Response 200 (application/json) ``` /users/sean/notes/ratings ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 + Body [ { "attached_to": { "type": "rating" }, "type": "movie", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 1, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } }, "note":{ "id":49, "notes":"Only watch the extended edition.", "privacy":"private", "spoiler":false, "created_at":"2023-09-07T20:10:18.000Z", "updated_at":"2023-09-07T20:10:56.000Z", "user":{ "username":"justin", "private":false, "name":"Justin Nemeth", "vip":true, "vip_ep":true, "ids":{ "slug":"justin", "trakt":1 } } } } ] ## Lists [/users/{id}/lists] + Parameters + id (required, string, `sean`) ... User slug ### Get a user's personal lists [GET] #### 🔓 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "name": "Star Wars in machete order", "description": "Next time you want to introduce someone to Star Wars for the first time, watch the films with them in this order: IV, V, II, III, VI.", "privacy": "public", "share_link": "https://trakt.tv/lists/55", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 55, "slug": "star-wars-in-machete-order" } }, { "name": "Vampires FTW", "description": "These suck, but in a good way!", "privacy": "link", "share_link": "https://trakt.tv/lists/share/83cea6a8252e6ec9cc74e72ce9d8fde7", "type": "personal", "display_numbers": false, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 52, "slug": "vampires-ftw" } } ] ### Create personal list [POST] #### 🔥 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` | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "name": "Star Wars in machete order", "description": "Next time you want to introduce someone to Star Wars for the first time, watch the films with them in this order: IV, V, II, III, VI.", "privacy": "public", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc" } + Response 201 (application/json) + Body { "name": "Star Wars in machete order", "description": "Next time you want to introduce someone to Star Wars for the first time, watch the films with them in this order: IV, V, II, III, VI.", "privacy": "public", "share_link": "https://trakt.tv/lists/55", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 0, "comment_count": 0, "likes": 0, "ids": { "trakt": 55, "slug": "star-wars-in-machete-order" } } + Response 420 (application/json) + Headers X-Upgrade-URL: https://trakt.tv/vip X-VIP-User: false X-Account-Limit: 5 ## Reorder Lists [/users/{id}/lists/reorder] + Parameters + id (required, string, `sean`) ... User slug ### Reorder a user's lists [POST] #### 🔒 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. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "rank": [ 823, 224, 88768, 356456, 245, 2, 890 ] } + Response 200 (application/json) + Body { "updated": 6, "skipped_ids": [2] } ## Collaborations [/users/{id}/lists/collaborations] + Parameters + id (required, string, `sean`) ... User slug ### Get all lists a user can collaborate on [GET] #### 🔓 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "name": "Our Favorite Movies", "description": "Hey everyone, add your favorite movies we've all enjoyed together over the years!", "privacy": "private", "share_link": "https://trakt.tv/lists/2612438", "type": "personal", "display_numbers": false, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2022-02-16T21:48:18.000Z", "updated_at": "2022-06-10T21:55:05.000Z", "item_count": 6, "comment_count": 0, "likes": 1, "ids": { "trakt": 2612438, "slug": "our-favorite-movies" }, "user": { "username": "sean", "private": false, "name": "Sean", "vip": true, "vip_ep": false, "ids": { "slug": "sean", "trakt": 2 } } } ] ## List [/users/{id}/lists/{list_id}] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug ### Get personal list [GET] #### 🔓 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body { "name": "Star Wars in machete order", "description": "Next time you want to introduce someone to Star Wars for the first time, watch the films with them in this order: IV, V, II, III, VI.", "privacy": "public", "share_link": "https://trakt.tv/lists/55", "type": "personal", "display_numbers": true, "allow_comments": true, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 55, "slug": "star-wars-in-machete-order" }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ### Update personal list [PUT] #### 🔒 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` | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "name": "Star Wars in NEW machete order", "privacy": "private", "display_numbers": false, "sort_by": "rank", "sort_how": "asc" } + Response 200 (application/json) + Body { "name": "Star Wars in NEW machete order", "description": "Next time you want to introduce someone to Star Wars for the first time, watch the films with them in this order: IV, V, II, III, VI.", "privacy": "private", "share_link": "https://trakt.tv/lists/55", "type": "personal", "display_numbers": true, "allow_comments": false, "sort_by": "rank", "sort_how": "asc", "created_at": "2014-10-11T17:00:54.000Z", "updated_at": "2014-10-11T17:00:54.000Z", "item_count": 5, "comment_count": 0, "likes": 0, "ids": { "trakt": 55, "slug": "star-wars-in-machete-order" }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ### Delete a user's personal list [DELETE] #### 🔒 OAuth Required Remove a personal list and all items it contains. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ## List Likes [/users/{id}/lists/{list_id}/likes] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug ### Get all users who liked a list [GET] #### 🔓 OAuth Optional 📄 Pagination Returns all users who liked a list. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 1 X-Pagination-Item-Count: 5 X-List-ID: 1 + Body [ { "liked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, { "liked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## List Like [/users/{id}/lists/{list_id}/like] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug ### Like a list [POST] #### 🔒 OAuth Required Votes help determine popular lists. Only one like is allowed per list per user. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ### Remove like on a list [DELETE] #### 🔒 OAuth Required Remove a like on a list. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 ## List Items [/users/{id}/lists/{list_id}/items/{type}/{sort_by}/{sort_how}] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug + type (optional, string, `movies`) ... Filter for a specific item type + Values + `movie` + `show` + `season` + `episode` + `person` + sort_by (optional, string, `rank`) ... Sort by a specific property + Values + `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 (optional, string, `asc`) ... Sort direction + Values + `asc` + `desc` ### Get items on a personal list [GET] #### 🔥 **VIP Enhanced** 🔓 OAuth Optional 📄 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. #### Notes Each list item contains a `notes` field with text entered by the user. #### Sorting Default sorting is based on the list defaults and sent in the `X-Sort-By` and `X-Sort-How` headers. If you specify the `sort_by` and `sort_how` parameters, the response will be sorted based on those values and sent in the `X-Applied-Sort-By` and `X-Applied-Sort-How` headers. Some `sort_by` options are 🔥 **VIP Only** including `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, and `tmdb_votes`. If sent for a non VIP, the items will fall back to `rank`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Private-User: false X-Sort-By: rank X-Sort-How: asc X-List-ID: 1 + Body [ { "rank": 1, "id": 101, "listed_at": "2014-06-16T06:07:12.000Z", "notes": "You are part of the rebel alliance and a spy!", "type": "movie", "movie": { "title": "Star Wars: Episode IV - A New Hope", "year": 1977, "ids": { "trakt": 12, "slug": "star-wars-episode-iv-a-new-hope-1977", "imdb": "tt0076759", "tmdb": 11 } } }, { "rank": 2, "id": 102, "listed_at": "2014-06-16T06:07:12.000Z", "notes": null, "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } }, { "rank": 3, "id": 103, "listed_at": "2014-06-16T06:07:12.000Z", "notes": null, "type": "season", "season": { "number": 1, "ids": { "tvdb": 30272, "tmdb": 3572 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 4, "id": 104, "listed_at": "2014-06-17T06:52:03.000Z", "notes": null, "type": "episode", "episode": { "season": 0, "number": 2, "title": "Wedding Day", "ids": { "trakt": 2, "tvdb": 3859791, "imdb": null, "tmdb": 62133 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 5, "id": 105, "listed_at": "2014-06-17T06:52:03.000Z", "notes": null, "type": "person", "person": { "name": "Garrett Hedlund", "ids": { "trakt": 1, "slug": "garrett-hedlund", "imdb": "nm1330560", "tmdb": 9828 } } } ] ## Add List Items [/users/{id}/lists/{list_id}/items] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug ### Add items to personal list [POST] #### 🔥 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "ids": { "trakt": 1 }, "notes": "Amazing movie!" }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "ids": { "trakt": 1 } }, { "seasons": [ { "number": 1 } ], "ids": { "trakt": 1 }, "notes": "Best season of this show, don't bother watching the rest." }, { "seasons": [ { "number": 1, "episodes": [ { "number": 1 }, { "number": 2 } ] } ], "ids": { "trakt": 1 } } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ], "people": [ { "name": "Jeff Bridges", "ids": { "trakt": 2, "slug": "jeff-bridges", "imdb": "nm0000313", "tmdb": 1229 } } ] } + Response 201 (application/json) + Body { "added": { "movies": 1, "shows": 1, "seasons": 1, "episodes": 2, "people": 1 }, "existing": { "movies": 0, "shows": 0, "seasons": 0, "episodes": 0, "people": 0 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [], "people": [] }, "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 6 } } + Response 420 (application/json) + Headers X-Upgrade-URL: https://trakt.tv/vip X-VIP-User: false X-Account-Limit: 250 ## Remove List Items [/users/{id}/lists/{list_id}/items/remove] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug ### Remove items from personal list [POST] #### 🔒 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. | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "movies": [ { "ids": { "trakt": 1 } }, { "ids": { "imdb": "tt0000111" } } ], "shows": [ { "ids": { "trakt": 1 } }, { "seasons": [ { "number": 1 } ], "ids": { "trakt": 1 } }, { "seasons": [ { "number": 1, "episodes": [ { "number": 1 }, { "number": 2 } ] } ], "ids": { "trakt": 1 } } ], "seasons": [ { "ids": { "trakt": 140912, "tvdb": 703353, "tmdb": 81266 } } ], "episodes": [ { "ids": { "trakt": 1061, "tvdb": 1555111, "imdb": "tt007404", "tmdb": 422183 } } ], "people": [ { "name": "Jeff Bridges", "ids": { "trakt": 2, "slug": "jeff-bridges", "imdb": "nm0000313", "tmdb": 1229 } } ] } + Response 200 (application/json) + Body { "deleted": { "movies": 1, "shows": 1, "seasons": 1, "episodes": 2, "people": 1 }, "not_found": { "movies": [ { "ids": { "imdb": "tt0000111" } } ], "shows": [], "seasons": [], "episodes": [], "people": [] }, "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 0 } } ## Reorder List Items [/users/{id}/lists/{list_id}/items/reorder] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug ### Reorder items on a list [POST] #### 🔒 OAuth Required Reorder all items on a list by sending the updated `rank` of list item ids. Use the [**/users/:id/lists/:list_id/items**](#reference/users/list-items) method to get all list item ids. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "rank": [ 923, 324, 98768, 456456, 345, 12, 990 ] } + Response 200 (application/json) + Body { "updated": 6, "skipped_ids": [12], "list": { "updated_at": "2022-04-27T21:40:41.000Z", "item_count": 6 } } ## Update List Item [/users/{id}/lists/{list_id}/items/{list_item_id}] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug + list_item_id (required, integer, `1337`) ... List Item ID ### Update a list item [PUT] #### 🔥 VIP Only 🔒 OAuth Required 😁 Emojis Update the `notes` on a single list item. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "notes": "This is a great movie!" } + Response 204 (application/json) ## List Comments [/users/{id}/lists/{list_id}/comments/{sort}] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `plays` + `rating` + `added` ### Get all list comments [GET] #### 🔓 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 X-List-ID: 1 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Can't wait to watch everything on this epic list!", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## List Report [/users/{id}/lists/{list_id}/report] + Parameters + id (required, string, `sean`) ... User slug + list_id (required, string, `star-wars-in-machete-order`) ... Trakt ID or Trakt slug ### Report a user's list [POST] #### 🔒 OAuth Required Report a user's 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "spam", "message": "This list is spam." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: duplicate, remove, metadata, adult, language, spam, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." } ## Follow [/users/{id}/follow] + Parameters + id (required, string, `sean`) ... User slug ### Follow this user [POST] #### 🔒 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). > ### 🅽🅾🆃🅴 > _If this user is already being followed or there is a pending follow request, a `409` HTTP status code will returned._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 201 (application/json) + Body { "approved_at": "2014-11-15T09:41:34.704Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ### Unfollow this user [DELETE] #### 🔒 OAuth Required Unfollow someone you already follow. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ## Blocked Users [/users/blocked] ### Get blocked users [GET] #### 🔒 OAuth Required Returns all users you have blocked, including when each user was blocked. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "blocked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, { "blocked_at": "2014-09-01T09:10:11.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## Block [/users/{id}/block] + Parameters + id (required, string, `sean`) ... User slug ### Block this user [POST] #### 🔒 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. > ### 🅽🅾🆃🅴 > _If the user is already blocked, or you try to block yourself, a `409` HTTP status code will be returned._ + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 201 (application/json) ### Unblock this user [DELETE] #### 🔒 OAuth Required Unblock a user you previously blocked. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 204 (application/json) ## Followers [/users/{id}/followers] + Parameters + id (required, string, `sean`) ... User slug ### Get followers [GET] #### 🔓 OAuth Optional ✨ Extended Info Returns all followers including when the relationship began. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "followed_at": "2014-09-01T09:10:11.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, { "followed_at": "2014-09-01T09:10:11.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## Following [/users/{id}/following] + Parameters + id (required, string, `sean`) ... User slug ### Get following [GET] #### 🔓 OAuth Optional ✨ Extended Info Returns all user's they follow including when the relationship began. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "followed_at": "2014-09-01T09:10:11.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, { "followed_at": "2014-09-01T09:10:11.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## Friends [/users/{id}/friends] + Parameters + id (required, string, `sean`) ... User slug ### Get friends [GET] #### 🔓 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body [ { "friends_at": "2014-09-01T09:10:11.000Z", "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } }, { "friends_at": "2014-09-01T09:10:11.000Z", "user": { "username": "justin", "private": false, "name": "Justin Nemeth", "vip": true, "vip_ep": false, "ids": { "slug": "justin" } } } ] ## History [/users/{id}/history/{type}/{item_id}{?start_at,end_at}] + Parameters + id (required, string, `sean`) ... User slug + type (optional, string, `movies`) ... + Values + `movies` + `shows` + `seasons` + `episodes` + item_id (optional, integer, `123`) ... Trakt ID for a specific item. + start_at (optional, string, `2016-06-01T00:00:00.000Z`) ... Starting date. + end_at (optional, string, `2016-07-01T23:59:59.000Z`) ... Ending date. ### Get watched history [GET] #### 🔓 OAuth Optional 📄 Pagination ✨ Extended Info Returns movies and episodes that a user has watched, sorted by most recent. You can optionally limit the `type` to `movies` or `episodes`. The `id` _(64-bit integer)_ in each history item uniquely identifies the event and can be used to remove individual events by using the [**/sync/history/remove**](#reference/sync/remove-from-history/get-watched-history) method. The `action` will be set to `scrobble`, `checkin`, or `watch`. Specify a `type` and trakt `item_id` to limit the history for just that item. If the `item_id` is valid, but there is no history, an empty array will be returned. | Example URL | Returns watches for... | |---|---| | `/history/movies/12601` | TRON: Legacy | | `/history/shows/1388` | All episodes of Breaking Bad | | `/history/seasons/3950` | All episodes of Breaking Bad: Season 1 | | `/history/episodes/73482` | Only episode 1 for Breaking Bad: Season 1 | + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/history ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 1982346, "watched_at": "2014-03-31T09:28:53.000Z", "action": "scrobble", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "id": 1982347, "watched_at": "2014-02-27T09:28:53.000Z", "action": "checkin", "type": "episode", "episode": { "season": 2, "number": 1, "title": "Pawnee Zoo", "ids": { "trakt": 251, "tvdb": 797571, "imdb": null, "tmdb": 397629 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } }, { "id": 1982348, "watched_at": "2013-06-15T05:54:27.000Z", "action": "watch", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } } ] + Response 200 (application/json) ``` /users/sean/history/movies ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 1982346, "watched_at": "2014-03-31T09:28:53.000Z", "action": "scrobble", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } }, { "id": 1982347, "watched_at": "2013-12-07T09:04:59.000Z", "action": "checkin", "type": "movie", "movie": { "title": "Thor: The Dark World", "year": 2013, "ids": { "trakt": 10, "slug": "thor-the-dark-world-2013", "imdb": "tt1981115", "tmdb": 76338 } } }, { "id": 1982348, "watched_at": "2013-06-15T05:54:27.000Z", "action": "watch", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } } ] + Response 200 (application/json) ``` /users/sean/history/episodes ``` + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 1982346, "watched_at": "2014-03-31T09:28:53.000Z", "action": "scrobble", "type": "episode", "episode": { "season": 2, "number": 1, "title": "Pawnee Zoo", "ids": { "trakt": 251, "tvdb": 797571, "imdb": null, "tmdb": 397629 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } }, { "id": 1982347, "watched_at": "2014-03-31T09:28:53.000Z", "action": "checkin", "type": "episode", "episode": { "season": 2, "number": 2, "title": "The Stakeout", "ids": { "trakt": 252, "tvdb": 1088031, "imdb": null, "tmdb": 397627 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } }, { "id": 1982348, "watched_at": "2014-03-31T09:28:53.000Z", "action": "watch", "type": "episode", "episode": { "season": 2, "number": 3, "title": "Beauty Pageant", "ids": { "trakt": 253, "tvdb": 1088041, "imdb": null, "tmdb": 397642 } }, "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } } ] ## Ratings [/users/{id}/ratings/{type}/{rating}] + Parameters + id (required, string, `sean`) ... User slug + type (optional, string, `movies`) ... + Values + `movies` + `shows` + `seasons` + `episodes` + `all` + rating (optional, integer, `9`) ... Filter for a specific rating. + Values + `1` + `2` + `3` + `4` + `5` + `6` + `7` + `8` + `9` + `10` ### Get ratings [GET] #### 🔓 OAuth Optional 📄 Pagination Optional ✨ Extended Info Get a user's ratings filtered by `type`. You can optionally filter for a specific `rating` between 1 and 10. Send a comma separated string for `rating` if you need multiple ratings. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/ratings/movies ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /users/sean/ratings/shows ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] + Response 200 (application/json) ``` /users/sean/ratings/seasons ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 8, "type": "season", "season": { "number": 0, "ids": { "tvdb": 439371, "tmdb": 3577 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 9, "type": "season", "season": { "number": 1, "ids": { "tvdb": 30272, "tmdb": 3572 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] + Response 200 (application/json) ``` /users/sean/ratings/episodes ``` + Body [ { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "episode", "episode": { "season": 4, "number": 1, "title": "Box Cutter", "ids": { "trakt": 49, "tvdb": 2639411, "imdb": "tt1683084", "tmdb": 62118 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rated_at": "2014-09-01T09:10:11.000Z", "rating": 10, "type": "episode", "episode": { "season": 4, "number": 8, "title": "Hermanos", "ids": { "trakt": 56, "tvdb": 4127161, "imdb": "tt1683095", "tmdb": 62127 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] ## Watchlist [/users/{id}/watchlist/{type}/{sort_by}/{sort_how}] + Parameters + id (required, string, `sean`) ... User slug + type (optional, string, `all`) ... Filter for a specific item type + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + sort_by (optional, string, `rank`) ... Sort by a specific property + Values + `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 (optional, string, `asc`) ... Sort direction + Values + `asc` + `desc` ### Get watchlist [GET] #### 🔥 **VIP Enhanced** 🔓 OAuth Optional 📄 Pagination Optional ✨ Extended Info 😁 Emojis Returns all items in a user's watchlist filtered by type. > ### ☣️ 🅸🅼🅿🅾🆁🆃🅰🅽🆃 > The watchlist should not be used as a list of what the user is actively watching. Use a combination of the [**/sync/watched**](/reference/sync/get-watched) and [**/shows/:id/progress**](/reference/shows/watched-progress) methods to get what the user is actively watching. #### Notes Each watchlist item contains a `notes` field with text entered by the user. #### Sorting Default sorting is based on the list defaults and sent in the `X-Sort-By` and `X-Sort-How` headers. If you specify the `sort_by` and `sort_how` parameters, the response will be sorted based on those values and sent in the `X-Applied-Sort-By` and `X-Applied-Sort-How` headers. Some `sort_by` options are 🔥 **VIP Only** including `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, and `tmdb_votes`. If sent for a non VIP, the items will fall back to `rank`. #### Auto Removal When an item is watched, it will be automatically removed from the watchlist. For shows and seasons, watching 1 episode will remove the entire show or season. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/watchlist/movies ``` + Headers X-Private-User: false X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Need to catch up before TRON 3 is out.", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Really need to check out Heath Ledger's performance in this.", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /users/sean/watchlist/shows ``` + Headers X-Private-User: false X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "How have I not watched this yet?", "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] + Response 200 (application/json) ``` /users/sean/watchlist/seasons ``` + Headers X-Private-User: false X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "season", "season": { "number": 3, "ids": { "tvdb": 171641, "tmdb": 3575 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "season", "season": { "number": 1, "ids": { "tvdb": 30272, "tmdb": 3572 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] + Response 200 (application/json) ``` /users/sean/watchlist/episodes ``` + Headers X-Private-User: false X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "episode", "episode": { "season": 4, "number": 1, "title": "Box Cutter", "ids": { "trakt": 49, "tvdb": 2639411, "imdb": "tt1683084", "tmdb": 62118 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": null, "type": "episode", "episode": { "season": 4, "number": 8, "title": "Hermanos", "ids": { "trakt": 56, "tvdb": 4127161, "imdb": "tt1683095", "tmdb": 62127 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } ] ## Watchlist Comments [/users/{id}/watchlist/comments/{sort}] + Parameters + id (required, string, `sean`) ... User slug + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `plays` + `rating` + `added` ### Get all favorites comments [GET] #### 🔓 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Can't wait to watch everything on this epic list!", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Favorites [/users/{id}/favorites/{type}/{sort_by}/{sort_how}] + Parameters + id (required, string, `sean`) ... User slug + type (optional, string, `all`) ... Filter for a specific item type + Values + `all` + `movies` + `shows` + `seasons` + `episodes` + sort_by (optional, string, `rank`) ... Sort by a specific property + Values + `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 (optional, string, `asc`) ... Sort direction + Values + `asc` + `desc` ### Get favorites [GET] #### 🔥 **VIP Enhanced** 🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis Returns the top 100 shows and movies a user has favorited. Apps should encourage user's to add favorites so the algorithm keeps getting better. #### Notes Each favorite contains a `notes` field explaining why the user favorited the item. #### Sorting Default sorting is based on the list defaults and sent in the `X-Sort-By` and `X-Sort-How` headers. If you specify the `sort_by` and `sort_how` parameters, the response will be sorted based on those values and sent in the `X-Applied-Sort-By` and `X-Applied-Sort-How` headers. Some `sort_by` options are 🔥 **VIP Only** including `imdb_rating`, `tmdb_rating`, `rt_tomatometer`, `rt_audience`, `metascore`, `votes`, `imdb_votes`, and `tmdb_votes`. If sent for a non VIP, the items will fall back to `rank`. + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/justin/favorites/movies ``` + Headers X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Daft Punk really knocks it out of the park on the soundtrack.", "type": "movie", "movie": { "title": "TRON: Legacy", "year": 2010, "ids": { "trakt": 1, "slug": "tron-legacy-2010", "imdb": "tt1104001", "tmdb": 20526 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Heath Ledger's Joker transformation is truly epic.", "type": "movie", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 6, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /users/justin/favorites/shows ``` + Headers X-Sort-By: rank X-Sort-How: asc + Body [ { "rank": 1, "id": 101, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "I AM THE DANGER!", "type": "show", "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "rank": 2, "id": 102, "listed_at": "2014-09-01T09:10:11.000Z", "notes": "Atmospheric for days.", "type": "show", "show": { "title": "The Walking Dead", "year": 2010, "ids": { "trakt": 2, "slug": "the-walking-dead", "tvdb": 153021, "imdb": "tt1520211", "tmdb": 1402 } } } ] ## Favorites Comments [/users/{id}/favorites/comments/{sort}] + Parameters + id (required, string, `sean`) ... User slug + sort (optional, string, `likes`) ... how to sort + Values + `likes` + `likes_30` + `replies` + `replies_30` + `plays` + `rating` + `added` ### Get all favorites comments [GET] #### 🔓 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. > ### 🅽🅾🆃🅴 > _If you send OAuth, comments from blocked users will be automatically filtered out._ + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Headers X-Pagination-Page: 1 X-Pagination-Limit: 10 X-Pagination-Page-Count: 10 X-Pagination-Item-Count: 100 + Body [ { "id": 8, "parent_id": 0, "created_at": "2011-03-25T22:35:17.000Z", "updated_at": "2011-03-25T22:35:17.000Z", "comment": "Can't wait to watch everything on this epic list!", "spoiler": false, "review": false, "replies": 0, "likes": 0, "user_stats": { "rating": null, "play_count": 1, "completed_count": 1 }, "user": { "username": "sean", "private": false, "name": "Sean Rudford", "vip": true, "vip_ep": false, "ids": { "slug": "sean" } } } ] ## Watching [/users/{id}/watching] + Parameters + id (required, string, `sean`) ... User slug ### Get watching [GET] #### 🔓 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. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) Currently watching an `episode`. + Body { "expires_at": "2014-10-23T07:09:12.000Z", "started_at": "2014-10-23T06:24:12.000Z", "action": "scrobble", "type": "episode", "episode": { "season": 0, "number": 2, "title": "Wedding Day", "ids": { "trakt": 2, "tvdb": 3859791, "imdb": "", "tmdb": 62133 } }, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } } + Response 200 (application/json) Currently watching a `movie`. + Body { "expires_at": "2014-10-23T08:36:02.000Z", "started_at": "2014-10-23T06:44:02.000Z", "action": "checkin", "type": "movie", "movie": { "title": "Super 8", "year": 2011, "ids": { "trakt": 2, "slug": "super-8-2011", "imdb": "tt1650062", "tmdb": 37686 } } } + Response 204 (application/json) Not watching anything. + Body ## Watched [/users/{id}/watched/{type}] + Parameters + id (required, string, `sean`) ... User slug + type (required, string, `movies`) ... + Values + `movies` + `shows` ### Get watched [GET] #### 🔓 OAuth Optional ✨ Extended Info Returns all movies or shows a user has watched sorted by most recently watched. If `type` is set to _shows_ and you add `?extended=noseasons` to the URL, it won't return season or episode info. Each `movie` and `show` object contains `last_watched_at` and `last_updated_at` timestamps. Since users can set custom dates when they watched movies and episodes, it is possible for `last_watched_at` to be in the past. We also include `last_updated_at` to help sync Trakt data with your app. Cache this timestamp locally and only re-process the movies and shows if you see a newer timestamp. Each `show` object contains a `reset_at` timestamp. If not `null`, this 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`. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) ``` /users/sean/watched/movies ``` + Body [ { "plays": 4, "last_watched_at": "2014-10-11T17:00:54.000Z", "last_updated_at": "2014-10-11T17:00:54.000Z", "movie": { "title": "Batman Begins", "year": 2005, "ids": { "trakt": 6, "slug": "batman-begins-2005", "imdb": "tt0372784", "tmdb": 272 } } }, { "plays": 2, "last_watched_at": "2014-10-12T17:00:54.000Z", "last_updated_at": "2014-10-12T17:00:54.000Z", "movie": { "title": "The Dark Knight", "year": 2008, "ids": { "trakt": 4, "slug": "the-dark-knight-2008", "imdb": "tt0468569", "tmdb": 155 } } } ] + Response 200 (application/json) ``` /users/sean/watched/shows ``` + Body [ { "plays": 56, "last_watched_at": "2014-10-11T17:00:54.000Z", "last_updated_at": "2014-10-11T17:00:54.000Z", "reset_at": null, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] } ] }, { "plays": 23, "last_watched_at": "2014-10-12T17:00:54.000Z", "last_updated_at": "2014-10-12T17:00:54.000Z", "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } }, "seasons": [ { "number": 1, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] }, { "number": 2, "episodes": [ { "number": 1, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" }, { "number": 2, "plays": 1, "last_watched_at": "2014-10-11T17:00:54.000Z" } ] } ] } ] + Response 200 (application/json) ``` /users/sean/watched/shows?extended=noseasons ``` + Body [ { "plays": 56, "last_watched_at": "2014-10-11T17:00:54.000Z", "last_updated_at": "2014-10-11T17:00:54.000Z", "reset_at": null, "show": { "title": "Breaking Bad", "year": 2008, "ids": { "trakt": 1, "slug": "breaking-bad", "tvdb": 81189, "imdb": "tt0903747", "tmdb": 1396 } } }, { "plays": 23, "last_watched_at": "2014-10-12T17:00:54.000Z", "last_updated_at": "2014-10-12T17:00:54.000Z", "reset_at": "2019-10-12T17:00:54.000Z", "show": { "title": "Parks and Recreation", "year": 2009, "ids": { "trakt": 4, "slug": "parks-and-recreation", "tvdb": 84912, "imdb": "tt1266020", "tmdb": 8592 } } } ] ## Stats [/users/{id}/stats] + Parameters + id (required, string, `sean`) ... User slug ### Get stats [GET] #### 🔓 OAuth Optional Returns stats about the movies, shows, and episodes a user has watched, collected, and rated. + Request (application/json) + Headers trakt-api-version: 2 trakt-api-key: [client_id] + Response 200 (application/json) + Body { "movies": { "plays": 155, "watched": 114, "minutes": 15650, "collected": 933, "ratings": 256, "comments": 28 }, "shows": { "watched": 16, "collected": 7, "ratings": 63, "comments": 20 }, "seasons": { "ratings": 6, "comments": 1 }, "episodes": { "plays": 552, "watched": 534, "minutes": 17330, "collected": 117, "ratings": 64, "comments": 14 }, "network": { "friends": 1, "followers": 4, "following": 11 }, "ratings": { "total": 389, "distribution": { "1": 18, "2": 1, "3": 4, "4": 1, "5": 10, "6": 9, "7": 37, "8": 37, "9": 57, "10": 215 } } } ## Report [/users/{id}/report] + Parameters + id (required, string, `sean`) ... User slug ### Report a user [POST] #### 🔒 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`) | + Request (application/json) + Headers Authorization: Bearer [access_token] trakt-api-version: 2 trakt-api-key: [client_id] + Body { "reason": "spam", "message": "This user is posting spam in their profile." } + Response 201 (application/json) + Response 400 (application/json) + Body { "message": "reason is required and must be one of: spam, adult, language, other" } + Response 409 (application/json) + Body { "message": "You already have a pending report for this item." }