Search Link: https://www.apis.guru.com
Overview
- GET /calendars/all/dvd/{start_date}/{days}
- GET /calendars/all/movies/{start_date}/{days}
- GET /calendars/all/shows/new/{start_date}/{days}
- GET /calendars/all/shows/premieres/{start_date}/{days}
- GET /calendars/all/shows/{start_date}/{days}
- GET /calendars/my/dvd/{start_date}/{days}
- GET /calendars/my/movies/{start_date}/{days}
- GET /calendars/my/shows/new/{start_date}/{days}
- GET /calendars/my/shows/premieres/{start_date}/{days}
- GET /calendars/my/shows/{start_date}/{days}
- GET /certifications/{type}
- DELETE /checkin
- POST /checkin
- POST /comments
- GET /comments/recent/{comment_type}/{type}
- GET /comments/trending/{comment_type}/{type}
- GET /comments/updates/{comment_type}/{type}
- DELETE /comments/{id}
- GET /comments/{id}
- PUT /comments/{id}
- GET /comments/{id}/item
- DELETE /comments/{id}/like
- POST /comments/{id}/like
- GET /comments/{id}/likes
- GET /comments/{id}/replies
- POST /comments/{id}/replies
- GET /countries/{type}
- GET /genres/{type}
- GET /languages/{type}
- GET /lists/popular
- GET /lists/trending
- GET /lists/{id}
- GET /lists/{id}/comments/{sort}
- GET /lists/{id}/items/{type}
- GET /lists/{id}/likes
- GET /movies/anticipated
- GET /movies/boxoffice
- GET /movies/collected/{period}
- GET /movies/played/{period}
- GET /movies/popular
- GET /movies/recommended/{period}
- GET /movies/trending
- GET /movies/updates/id/{start_date}
- GET /movies/updates/{start_date}
- GET /movies/watched/{period}
- GET /movies/{id}
- GET /movies/{id}/aliases
- GET /movies/{id}/comments/{sort}
- GET /movies/{id}/lists/{type}/{sort}
- GET /movies/{id}/people
- GET /movies/{id}/ratings
- GET /movies/{id}/related
- GET /movies/{id}/releases/{country}
- GET /movies/{id}/stats
- GET /movies/{id}/studios
- GET /movies/{id}/translations/{language}
- GET /movies/{id}/watching
- GET /networks
- GET /oauth/authorize
- POST /oauth/device/code
- POST /oauth/device/token
- POST /oauth/revoke
- POST /oauth/token
- GET /people/updates/id/{start_date}
- GET /people/updates/{start_date}
- GET /people/{id}
- GET /people/{id}/lists/{type}/{sort}
- GET /people/{id}/movies
- GET /people/{id}/shows
- GET /recommendations/movies
- DELETE /recommendations/movies/{id}
- GET /recommendations/shows
- DELETE /recommendations/shows/{id}
- POST /scrobble/pause
- POST /scrobble/start
- POST /scrobble/stop
- GET /search/{id_type}/{id}
- GET /search/{type}
- GET /shows/anticipated
- GET /shows/collected/{period}
- GET /shows/played/{period}
- GET /shows/popular
- GET /shows/recommended/{period}
- GET /shows/trending
- GET /shows/updates/id/{start_date}
- GET /shows/updates/{start_date}
- GET /shows/watched/{period}
- GET /shows/{id}
- GET /shows/{id}/aliases
- GET /shows/{id}/certifications
- GET /shows/{id}/comments/{sort}
- GET /shows/{id}/last_episode
- GET /shows/{id}/lists/{type}/{sort}
- GET /shows/{id}/next_episode
- GET /shows/{id}/people
- GET /shows/{id}/progress/collection
- GET /shows/{id}/progress/watched
- DELETE /shows/{id}/progress/watched/reset
- POST /shows/{id}/progress/watched/reset
- GET /shows/{id}/ratings
- GET /shows/{id}/related
- GET /shows/{id}/seasons
- GET /shows/{id}/seasons/{season}
- GET /shows/{id}/seasons/{season}/comments/{sort}
- GET /shows/{id}/seasons/{season}/episodes/{episode}
- GET /shows/{id}/seasons/{season}/episodes/{episode}/comments/{sort}
- GET /shows/{id}/seasons/{season}/episodes/{episode}/lists/{type}/{sort}
- GET /shows/{id}/seasons/{season}/episodes/{episode}/people
- GET /shows/{id}/seasons/{season}/episodes/{episode}/ratings
- GET /shows/{id}/seasons/{season}/episodes/{episode}/stats
- GET /shows/{id}/seasons/{season}/episodes/{episode}/translations/{language}
- GET /shows/{id}/seasons/{season}/episodes/{episode}/watching
- GET /shows/{id}/seasons/{season}/lists/{type}/{sort}
- GET /shows/{id}/seasons/{season}/people
- GET /shows/{id}/seasons/{season}/ratings
- GET /shows/{id}/seasons/{season}/stats
- GET /shows/{id}/seasons/{season}/translations/{language}
- GET /shows/{id}/seasons/{season}/watching
- GET /shows/{id}/stats
- GET /shows/{id}/studios
- GET /shows/{id}/translations/{language}
- GET /shows/{id}/watching
- POST /sync/collection
- POST /sync/collection/remove
- GET /sync/collection/{type}
- POST /sync/history
- POST /sync/history/remove
- GET /sync/history/{type}/{id}
- GET /sync/last_activities
- DELETE /sync/playback/{id}
- GET /sync/playback/{type}
- POST /sync/ratings
- POST /sync/ratings/remove
- GET /sync/ratings/{type}/{rating}
- POST /sync/recommendations
- POST /sync/recommendations/remove
- POST /sync/recommendations/reorder
- GET /sync/recommendations/{type}/{sort}
- GET /sync/watched/{type}
- POST /sync/watchlist
- POST /sync/watchlist/remove
- POST /sync/watchlist/reorder
- GET /sync/watchlist/{type}/{sort}
- GET /users/hidden/{section}
- POST /users/hidden/{section}
- POST /users/hidden/{section}/remove
- GET /users/requests
- GET /users/requests/following
- DELETE /users/requests/{id}
- POST /users/requests/{id}
- GET /users/saved_filters/{section}
- GET /users/settings
- GET /users/{id}
- GET /users/{id}/collection/{type}
- GET /users/{id}/comments/{comment_type}/{type}
- DELETE /users/{id}/follow
- POST /users/{id}/follow
- GET /users/{id}/followers
- GET /users/{id}/following
- GET /users/{id}/friends
- GET /users/{id}/history/{type}/{item_id}
- GET /users/{id}/likes/{type}
- GET /users/{id}/lists
- POST /users/{id}/lists
- GET /users/{id}/lists/collaborations
- POST /users/{id}/lists/reorder
- DELETE /users/{id}/lists/{list_id}
- GET /users/{id}/lists/{list_id}
- PUT /users/{id}/lists/{list_id}
- GET /users/{id}/lists/{list_id}/comments/{sort}
- POST /users/{id}/lists/{list_id}/items
- POST /users/{id}/lists/{list_id}/items/remove
- POST /users/{id}/lists/{list_id}/items/reorder
- GET /users/{id}/lists/{list_id}/items/{type}
- DELETE /users/{id}/lists/{list_id}/like
- POST /users/{id}/lists/{list_id}/like
- GET /users/{id}/lists/{list_id}/likes
- GET /users/{id}/ratings/{type}/{rating}
- GET /users/{id}/recommendations/{type}/{sort}
- GET /users/{id}/stats
- GET /users/{id}/watched/{type}
- GET /users/{id}/watching
- GET /users/{id}/watchlist/{type}/{sort}
GET /calendars/all/dvd/{start_date}/{days}
Summary: Get DVD releases
✨ Extended Info 🎚 Filters
Returns all movies with a DVD release date during the time period specified.
OpenAPI snippet URL
GET /calendars/all/movies/{start_date}/{days}
Summary: Get movies
✨ Extended Info 🎚 Filters
Returns all movies with a release date during the time period specified.
OpenAPI snippet URL
GET /calendars/all/shows/new/{start_date}/{days}
Summary: Get new shows
✨ Extended Info 🎚 Filters
Returns all new show premieres (season 1, episode 1) airing during the time period specified.
OpenAPI snippet URL
GET /calendars/all/shows/premieres/{start_date}/{days}
Summary: Get season premieres
✨ Extended Info 🎚 Filters
Returns all show premieres (any season, episode 1) airing during the time period specified.
OpenAPI snippet URL
GET /calendars/all/shows/{start_date}/{days}
Summary: Get shows
✨ Extended Info 🎚 Filters
Returns all shows airing during the time period specified.
OpenAPI snippet URL
GET /calendars/my/dvd/{start_date}/{days}
Summary: Get DVD releases
🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all movies with a DVD release date during the time period specified.
OpenAPI snippet URL
GET /calendars/my/movies/{start_date}/{days}
Summary: Get movies
🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all movies with a release date during the time period specified.
OpenAPI snippet URL
GET /calendars/my/shows/new/{start_date}/{days}
Summary: Get new shows
🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all new show premieres (season 1, episode 1) airing during the time period specified.
OpenAPI snippet URL
GET /calendars/my/shows/premieres/{start_date}/{days}
Summary: Get season premieres
🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all show premieres (any season, episode 1) airing during the time period specified.
OpenAPI snippet URL
GET /calendars/my/shows/{start_date}/{days}
Summary: Get shows
🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all shows airing during the time period specified.
OpenAPI snippet URL
GET /certifications/{type}
Summary: Get certifications
Get a list of all certifications, including names, slugs, and descriptions.
OpenAPI snippet URL
DELETE /checkin
Summary: Delete any active checkins
🔒 OAuth Required
Removes any active checkins, no need to provide a specific item.
OpenAPI snippet URL
POST /checkin
Summary: Check into an item
🔒 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. |
venue_id | string | Foursquare venue ID. |
venue_name | string | Foursquare venue name. |
app_version | string | Version number of the app. |
app_date | string | Build date of the app. |
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 method.
| Key | Type |
|---|---|
twitter | boolean |
tumblr | boolean |
Note: If a checkin is already in progress, a 409 HTTP status code will returned. The response will contain an expires_at timestamp which is when the user can check in again.
OpenAPI snippet URL
POST /comments
Summary: Post a comment
🔒 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 method.
| Key | Type |
|---|---|
twitter | boolean |
tumblr | boolean |
medium | boolean |
OpenAPI snippet URL
GET /comments/recent/{comment_type}/{type}
Summary: Get recently created comments
📄 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.
OpenAPI snippet URL
GET /comments/trending/{comment_type}/{type}
Summary: Get trending comments
📄 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.
OpenAPI snippet URL
GET /comments/updates/{comment_type}/{type}
Summary: Get recently updated comments
📄 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.
OpenAPI snippet URL
DELETE /comments/{id}
Summary: Delete a comment or reply
🔒 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.
OpenAPI snippet URL
GET /comments/{id}
Summary: Get a comment or reply
😁 Emojis
Returns a single comment and indicates how many replies it has. Use /comments/:id/replies to get the actual replies.
OpenAPI snippet URL
PUT /comments/{id}
Summary: Update a comment or reply
🔒 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? |
OpenAPI snippet URL
GET /comments/{id}/item
Summary: Get the attached media item
✨ 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.
OpenAPI snippet URL
DELETE /comments/{id}/like
Summary: Remove like on a comment
🔒 OAuth Required
Remove a like on a comment.
OpenAPI snippet URL
POST /comments/{id}/like
Summary: Like a comment
🔒 OAuth Required
Votes help determine popular comments. Only one like is allowed per comment per user.
OpenAPI snippet URL
GET /comments/{id}/likes
Summary: Get all users who liked a comment
📄 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.
OpenAPI snippet URL
GET /comments/{id}/replies
Summary: Get replies for a comment
📄 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 again with the new comment id.
OpenAPI snippet URL
POST /comments/{id}/replies
Summary: Post a reply for a comment
🔒 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.
JSON POST Data
| Key | Type | Default | Value |
|---|---|---|---|
comment * | string | Text for the reply. | |
spoiler | boolean | false | Is this a spoiler? |
OpenAPI snippet URL
GET /countries/{type}
Summary: Get countries
Get a list of all countries, including names and codes.
OpenAPI snippet URL
GET /genres/{type}
Summary: Get genres
Get a list of all genres, including names and slugs.
OpenAPI snippet URL
GET /languages/{type}
Summary: Get languages
Get a list of all langauges, including names and codes.
OpenAPI snippet URL
GET /lists/popular
Summary: Get popular lists
📄 Pagination 😁 Emojis
Returns the most popular lists. Popularity is calculated using total number of likes and comments.
OpenAPI snippet URL
GET /lists/trending
Summary: Get trending lists
📄 Pagination 😁 Emojis
Returns all lists with the most likes and comments over the last 7 days.
OpenAPI snippet URL
GET /lists/{id}
Summary: Get list
😁 Emojis
Returns a single list. Use the /lists/:id/items method to get the actual items this list contains.
Note: You must use an integer id, and only public lists will return data.
OpenAPI snippet URL
GET /lists/{id}/comments/{sort}
Summary: Get all list comments
📄 Pagination 😁 Emojis
Returns all top level comments for a list. By default, the newest comments are returned first. Other sorting options include oldest, most likes, and most replies.
OpenAPI snippet URL
GET /lists/{id}/items/{type}
Summary: Get items on a list
📄 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 Headers
All list items are sorted by ascending rank. We also send X-Sort-By and X-Sort-How headers which can be used to custom sort the list in your app based on the user’s preference. Values for X-Sort-By include rank, added, title, released, runtime, popularity, percentage, votes, my_rating, random, watched, and collected. Values for X-Sort-How include asc and desc.
OpenAPI snippet URL
GET /lists/{id}/likes
Summary: Get all users who liked a list
📄 Pagination
Returns all users who liked a list.
OpenAPI snippet URL
GET /movies/anticipated
Summary: Get the most anticipated movies
📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most anticipated movies based on the number of lists a movie appears on.
OpenAPI snippet URL
GET /movies/boxoffice
Summary: Get the weekend box office
✨ Extended Info
Returns the top 10 grossing movies in the U.S. box office last weekend. Updated every Monday morning.
OpenAPI snippet URL
GET /movies/collected/{period}
Summary: Get the most Collected movies
📄 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.
OpenAPI snippet URL
GET /movies/played/{period}
Summary: Get the most played movies
📄 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.
OpenAPI snippet URL
GET /movies/popular
Summary: Get popular movies
📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most popular movies. Popularity is calculated using the rating percentage and the number of ratings.
OpenAPI snippet URL
GET /movies/recommended/{period}
Summary: Get the most recommended movies
📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most recommended movies in the specified time period, defaulting to weekly. All stats are relative to the specific time period.
OpenAPI snippet URL
GET /movies/trending
Summary: Get trending movies
📄 Pagination ✨ Extended Info 🎚 Filters
Returns all movies being watched right now. Movies with the most users are returned first.
OpenAPI snippet URL
GET /movies/updates/id/{start_date}
Summary: Get recently updated movie Trakt IDs
📄 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.
Important! 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.
Note: The start_date can only be a maximum of 30 days in the past.
OpenAPI snippet URL
GET /movies/updates/{start_date}
Summary: Get recently updated movies
📄 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.
Important! 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.
Note: The start_date can only be a maximum of 30 days in the past.
OpenAPI snippet URL
GET /movies/watched/{period}
Summary: Get the most watched movies
📄 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.
OpenAPI snippet URL
GET /movies/{id}
Summary: Get a movie
✨ Extended Info
Returns a single movie’s details.
Note: When getting full extended info, the status field can have a value of released, in production, post production, planned, rumored, or canceled.
OpenAPI snippet URL
GET /movies/{id}/aliases
Summary: Get all movie aliases
Returns all title aliases for a movie. Includes country where name is different.
OpenAPI snippet URL
GET /movies/{id}/comments/{sort}
Summary: Get all movie comments
📄 Pagination 😁 Emojis
Returns all top level comments for a movie. By default, the newest comments are returned first. Other sorting options include oldest, most likes, most replies, highest rated, lowest rated, and most plays.
OpenAPI snippet URL
GET /movies/{id}/lists/{type}/{sort}
Summary: Get lists containing this movie
📄 Pagination 😁 Emojis
Returns all lists that contain this movie. By default, personal lists are returned sorted by the most popular.
OpenAPI snippet URL
GET /movies/{id}/people
Summary: Get all people for a movie
✨ 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.
OpenAPI snippet URL
GET /movies/{id}/ratings
Summary: Get movie ratings
Returns rating (between 0 and 10) and distribution for a movie.
OpenAPI snippet URL
GET /movies/{id}/related
Summary: Get related movies
📄 Pagination ✨ Extended Info
Returns related and similar movies.
OpenAPI snippet URL
GET /movies/{id}/releases/{country}
Summary: Get all movie releases
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.
OpenAPI snippet URL
GET /movies/{id}/stats
Summary: Get movie stats
Returns lots of movie stats.
OpenAPI snippet URL
GET /movies/{id}/studios
Summary: Get movie studios
Returns all studios for a movie.
OpenAPI snippet URL
GET /movies/{id}/translations/{language}
Summary: Get all movie translations
Returns all translations for a movie, including language and translated values for title, tagline and overview.
OpenAPI snippet URL
GET /movies/{id}/watching
Summary: Get users watching right now
✨ Extended Info
Returns all users watching this movie right now.
OpenAPI snippet URL
GET /networks
Summary: Get networks
Get a list of all TV networks, including the name.
OpenAPI snippet URL
GET /oauth/authorize
Summary: Authorize Application
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. Send signup=true if you prefer the account sign up page to be the default.
Note: You should use the normal https://trakt.tv hostname when creating this URL and not the API URL.
OpenAPI snippet URL
POST /oauth/device/code
Summary: Generate new device codes
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.
JSON POST Data
| Key | Type | Value |
|---|---|---|
client_id * | string | Get this from your app settings. |
OpenAPI snippet URL
POST /oauth/device/token
Summary: Poll for the access_token
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 3 months. 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 |
OpenAPI snippet URL
POST /oauth/revoke
Summary: Revoke an access_token
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. |
OpenAPI snippet URL
POST /oauth/token
Summary: Exchange refresh_token for access_token
Use the refresh_token to get a new access_token without asking the user to re-authenticate. The access_token is valid for 3 months 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 |
OpenAPI snippet URL
GET /people/updates/id/{start_date}
Summary: Get recently updated people Trakt IDs
📄 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.
Important! 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.
Note: The start_date can only be a maximum of 30 days in the past.
OpenAPI snippet URL
GET /people/updates/{start_date}
Summary: Get recently updated people
📄 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.
Important! 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.
Note: The start_date can only be a maximum of 30 days in the past.
OpenAPI snippet URL
GET /people/{id}
Summary: Get a single person
✨ 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.
OpenAPI snippet URL
GET /people/{id}/lists/{type}/{sort}
Summary: Get lists containing this person
📄 Pagination 😁 Emojis
Returns all lists that contain this person. By default, personal lists are returned sorted by the most popular.
OpenAPI snippet URL
GET /people/{id}/movies
Summary: Get movie credits
✨ 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.
OpenAPI snippet URL
GET /people/{id}/shows
Summary: Get show credits
✨ 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.
OpenAPI snippet URL
GET /recommendations/movies
Summary: Get movie recommendations
🔒 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.
OpenAPI snippet URL
DELETE /recommendations/movies/{id}
Summary: Hide a movie recommendation
🔒 OAuth Required
Hide a movie from getting recommended anymore.
OpenAPI snippet URL
GET /recommendations/shows
Summary: Get show recommendations
🔒 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.
OpenAPI snippet URL
DELETE /recommendations/shows/{id}
Summary: Hide a show recommendation
🔒 OAuth Required
Hide a show from getting recommended anymore.
OpenAPI snippet URL
POST /scrobble/pause
Summary: Pause watching in a media center
🔒 OAuth Required
Use this method when the video is paused. The playback progress will be saved and /sync/playback can be used to resume the video from this exact position. Unpause a video by calling the /scrobble/start method again.
JSON POST Data
| Key | Type | Value |
|---|---|---|
| item * | object | movie or episode object. (see examples →) |
progress * | float | Progress percentage between 0 and 100. |
app_version | string | Version number of the app. |
app_date | string | Build date of the app. |
OpenAPI snippet URL
POST /scrobble/start
Summary: Start watching in a media center
🔒 OAuth Required
Use this method when the video initially starts playing or is unpaused. This will remove any playback progress if it exists.
Note: A watching status will auto expire after the remaining runtime has elapsed. There is no need to call this method again while continuing to watch the same item.
JSON POST Data
| Key | Type | Value |
|---|---|---|
| item * | object | movie or episode object. (see examples →) |
progress * | float | Progress percentage between 0 and 100. |
app_version | string | Version number of the app. |
app_date | string | Build date of the app. |
OpenAPI snippet URL
POST /scrobble/stop
Summary: Stop or finish watching in a media center
🔒 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 less than 80%, it will be treated as a pause and the action will be set to pause. The playback progress will be saved and /sync/playback can be used to resume the video from this exact position.
Note: If you prefer to use a threshold higher than 80%, you should use /scrobble/pause yourself so it doesn’t create duplicate scrobbles.
JSON POST Data
| Key | Type | Value |
|---|---|---|
| item * | object | movie or episode object. (see examples →) |
progress * | flloat | Progress percentage between 0 and 100. |
app_version | string | Version number of the app. |
app_date | string | Build date of the app. |
Note: If the same item was just scrobbled, a 409 HTTP status code will returned to avoid scrobbling a duplicate. The response will contain a watched_at timestamp when the item was last scrobbled and a expires_at timestamp when the item can be scrobbled again.
OpenAPI snippet URL
GET /search/{id_type}/{id}
Summary: Get ID lookup results
📄 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 |
OpenAPI snippet URL
GET /search/{type}
Summary: Get text query results
📄 Pagination ✨ Extended Info 🎚 Filters
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 (Solr) 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, all 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 |
|---|---|
movie | title |
tagline | |
overview | |
people | |
translations | |
aliases | |
show | title |
overview | |
people | |
translations | |
aliases | |
episode | title |
overview | |
person | name |
biography | |
list | name |
description |
OpenAPI snippet URL
GET /shows/anticipated
Summary: Get the most anticipated shows
📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most anticipated shows based on the number of lists a show appears on.
OpenAPI snippet URL
GET /shows/collected/{period}
Summary: Get the most collected shows
📄 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.
OpenAPI snippet URL
GET /shows/played/{period}
Summary: Get the most played shows
📄 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.
OpenAPI snippet URL
GET /shows/popular
Summary: Get popular shows
📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most popular shows. Popularity is calculated using the rating percentage and the number of ratings.
OpenAPI snippet URL
GET /shows/recommended/{period}
Summary: Get the most recommended shows
📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most recommended shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.
OpenAPI snippet URL
GET /shows/trending
Summary: Get trending shows
📄 Pagination ✨ Extended Info 🎚 Filters
Returns all shows being watched right now. Shows with the most users are returned first.
OpenAPI snippet URL
GET /shows/updates/id/{start_date}
Summary: Get recently updated show Trakt IDs
📄 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.
Important! 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.
Note: The start_date can only be a maximum of 30 days in the past.
OpenAPI snippet URL
GET /shows/updates/{start_date}
Summary: Get recently updated shows
📄 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.
Important! 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.
Note: The start_date can only be a maximum of 30 days in the past.
OpenAPI snippet URL
GET /shows/watched/{period}
Summary: Get the most watched shows
📄 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.
OpenAPI snippet URL
GET /shows/{id}
Summary: Get a single show
✨ Extended Info
Returns a single shows’s details. If you request extended info, the airs object is relative to the show’s country. You can use the day, time, and timezone to construct your own date then convert it to whatever timezone your user is in.
Note: When getting full extended info, the status field can have a value of returning series (airing right now), continuing (airing right now), in production (airing soon), planned (in development), upcoming (in development), pilot, canceled, or ended.
OpenAPI snippet URL
GET /shows/{id}/aliases
Summary: Get all show aliases
Returns all title aliases for a show. Includes country where name is different.
OpenAPI snippet URL
GET /shows/{id}/certifications
Summary: Get all show certifications
Returns all content certifications for a show, including the country.
OpenAPI snippet URL
GET /shows/{id}/comments/{sort}
Summary: Get all show comments
📄 Pagination 😁 Emojis
Returns all top level comments for a show. By default, the newest comments are returned first. Other sorting options include oldest, most likes, most replies, highest rated, lowest rated, most plays, and highest watched percentage.
OpenAPI snippet URL
GET /shows/{id}/last_episode
Summary: Get last episode
✨ Extended Info
Returns the most recently aired episode. If no episode is found, a 204 HTTP status code will be returned.
OpenAPI snippet URL
GET /shows/{id}/lists/{type}/{sort}
Summary: Get lists containing this show
📄 Pagination 😁 Emojis
Returns all lists that contain this show. By default, personal lists are returned sorted by the most popular.
OpenAPI snippet URL
GET /shows/{id}/next_episode
Summary: Get next episode
✨ Extended Info
Returns the next scheduled to air episode. If no episode is found, a 204 HTTP status code will be returned.
OpenAPI snippet URL
GET /shows/{id}/people
Summary: Get all people for a show
✨ Extended Info
Returns all cast and crew for a show, including the episode_count for which they appears. Each cast member will have a characters array and a standard person object.
The crew object will be broken up by department into production, art, crew, costume & make-up, directing, writing, sound, camera, visual effects, lighting, editing, and created by (if there are people for those crew positions). Each of those members will have a jobs array and a standard person object.
Guest Stars
If you add ?extended=guest_stars to the URL, it will return all guest stars that appeared in at least 1 episode of the show.
Note: This returns a lot of data, so please only use this extended parameter if you actually need it!
OpenAPI snippet URL
GET /shows/{id}/progress/collection
Summary: Get show collection progress
🔒 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.
Note: Only aired episodes are used to calculate progress. Episodes in the future or without an air date are ignored.
OpenAPI snippet URL
GET /shows/{id}/progress/watched
Summary: Get show watched progress
🔒 OAuth Required
Returns watched progress for a show including details on all aired seasons and episodes. The next_episode will be the next episode the user should watch, if there are no upcoming episodes it will be set to null. If not null, the reset_at date is when the user started re-watching the show. Your app can adjust the progress by ignoring episodes with a last_watched_at prior to the reset_at.
By default, any hidden seasons will be removed from the response and stats. To include these and adjust the completion stats, set the hidden flag to true.
By default, specials will be excluded from the response. Set the specials flag to true to include season 0 and adjust the stats accordingly. If you’d like to include specials, but not adjust the stats, set count_specials to false.
By default, the last_episode and next_episode are calculated using the last aired episode the user has watched, even if they’ve watched older episodes more recently. To use their last watched episode for these calculations, set the last_activity flag to watched.
Note: Only aired episodes are used to calculate progress. Episodes in the future or without an air date are ignored.
OpenAPI snippet URL
DELETE /shows/{id}/progress/watched/reset
Summary: Undo reset show progress
🔒 OAuth Required 🔥 VIP Only
Undo the reset and have watched progress use all watched history for the show.
OpenAPI snippet URL
POST /shows/{id}/progress/watched/reset
Summary: Reset show progress
🔒 OAuth Required 🔥 VIP Only
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.
OpenAPI snippet URL
GET /shows/{id}/ratings
Summary: Get show ratings
Returns rating (between 0 and 10) and distribution for a show.
OpenAPI snippet URL
GET /shows/{id}/related
Summary: Get related shows
📄 Pagination ✨ Extended Info
Returns related and similar shows.
OpenAPI snippet URL
GET /shows/{id}/seasons
Summary: Get all seasons for a show
✨ Extended Info
Returns all seasons for a show including the number of episodes in each season.
Episodes
If you add ?extended=episodes to the URL, it will return all episodes for all seasons.
Note: This returns a lot of data, so please only use this extended parameter if you actually need it!
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}
Summary: Get single season for a show
✨ 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.
Note: This returns a lot of data, so please only use this parameter if you actually need it!
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/comments/{sort}
Summary: Get all season comments
📄 Pagination 😁 Emojis
Returns all top level comments for a season. By default, the newest comments are returned first. Other sorting options include oldest, most likes, most replies, highest rated, lowest rated, most plays, and highest watched percentage.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}
Summary: Get a single episode for a show
✨ Extended Info
Returns a single episode’s details. All date and times are in UTC and were calculated using the episode’s air_date and show’s country and air_time.
Note: If the first_aired is unknown, it will be set to null.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}/comments/{sort}
Summary: Get all episode comments
📄 Pagination 😁 Emojis
Returns all top level comments for an episode. By default, the newest comments are returned first. Other sorting options include oldest, most likes, most replies, highest rated, lowest rated, and most plays.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}/lists/{type}/{sort}
Summary: Get lists containing this episode
📄 Pagination 😁 Emojis
Returns all lists that contain this episode. By default, personal lists are returned sorted by the most popular.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}/people
Summary: Get all people for an episode
✨ Extended Info
Returns all cast and crew for an episode. Each cast member will have a characters array and a standard person object.
The crew object will be broken up by department into production, art, crew, costume & make-up, directing, writing, sound, camera, visual effects, lighting, and editing (if there are people for those crew positions). Each of those members will have a jobs array and a standard person object.
Guest Stars
If you add ?extended=guest_stars to the URL, it will return all guest stars that appeared in the episode.
Note: This returns a lot of data, so please only use this extended parameter if you actually need it!
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}/ratings
Summary: Get episode ratings
Returns rating (between 0 and 10) and distribution for an episode.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}/stats
Summary: Get episode stats
Returns lots of episode stats.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}/translations/{language}
Summary: Get all episode translations
Returns all translations for an episode, including language and translated values for title and overview.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/episodes/{episode}/watching
Summary: Get users watching right now
✨ Extended Info
Returns all users watching this episode right now.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/lists/{type}/{sort}
Summary: Get lists containing this season
📄 Pagination 😁 Emojis
Returns all lists that contain this season. By default, personal lists are returned sorted by the most popular.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/people
Summary: Get all people for a season
✨ 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.
Note: This returns a lot of data, so please only use this extended parameter if you actually need it!
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/ratings
Summary: Get season ratings
Returns rating (between 0 and 10) and distribution for a season.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/stats
Summary: Get season stats
Returns lots of season stats.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/translations/{language}
Summary: Get all season translations
Returns all translations for an season, including language and translated values for title and overview.
OpenAPI snippet URL
GET /shows/{id}/seasons/{season}/watching
Summary: Get users watching right now
✨ Extended Info
Returns all users watching this season right now.
OpenAPI snippet URL
GET /shows/{id}/stats
Summary: Get show stats
Returns lots of show stats.
OpenAPI snippet URL
GET /shows/{id}/studios
Summary: Get show studios
Returns all studios for a show.
OpenAPI snippet URL
GET /shows/{id}/translations/{language}
Summary: Get all show translations
Returns all translations for a show, including language and translated values for title and overview.
OpenAPI snippet URL
GET /shows/{id}/watching
Summary: Get users watching right now
✨ Extended Info
Returns all users watching this show right now.
OpenAPI snippet URL
POST /sync/collection
Summary: Add items to collection
🔒 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.
Note: 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. |
OpenAPI snippet URL
POST /sync/collection/remove
Summary: Remove items from collection
🔒 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. |
OpenAPI snippet URL
GET /sync/collection/{type}
Summary: Get collection
🔒 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.
OpenAPI snippet URL
POST /sync/history
Summary: Add items to watched history
🔒 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.
Note: 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). |
OpenAPI snippet URL
POST /sync/history/remove
Summary: Remove items from history
🔒 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 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. |
OpenAPI snippet URL
GET /sync/history/{type}/{id}
Summary: Get watched history
🔒 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 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 for Breaking Bad: Season 1 |
OpenAPI snippet URL
GET /sync/last_activities
Summary: Get last activity
🔒 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.
OpenAPI snippet URL
DELETE /sync/playback/{id}
Summary: Remove a playback item
🔒 OAuth Required
Remove a playback item from a user’s playback progress list. A 404 will be returned if the id is invalid.
OpenAPI snippet URL
GET /sync/playback/{type}
Summary: Get playback progress
🔒 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.
Note: We only save playback progress for the last 6 months.
OpenAPI snippet URL
POST /sync/ratings
Summary: Add new ratings
🔒 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. |
OpenAPI snippet URL
POST /sync/ratings/remove
Summary: Remove ratings
🔒 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. |
OpenAPI snippet URL
GET /sync/ratings/{type}/{rating}
Summary: Get ratings
🔒 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.
OpenAPI snippet URL
POST /sync/recommendations
Summary: Add items to personal recommendations
🔒 OAuth Required 😁 Emojis
If the user only had 50 movies and TV shows to bring with them on a desert island, what would they be? These recommendations are used to enchance Trakt’s social recommendation algorithm. Apps should encourage user’s to build their personal recommendations so the algorithm keeps getting better.
Notes
Each recommendation can optionally accept a notes (255 maximum characters) field explaining why the user recommended the item.
Limits
If the user has recommended 50 items already, 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. |
OpenAPI snippet URL
POST /sync/recommendations/remove
Summary: Remove items from personal recommendations
🔒 OAuth Required
Remove items from a user’s personal recommendations. These recommendations are used to enchance Trakt’s social recommendation algorithm. Apps should encourage user’s to build their personal recommendations 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. |
OpenAPI snippet URL
POST /sync/recommendations/reorder
Summary: Reorder personally recommended items
🔒 OAuth Required
Reorder all items on a user’s personal recommendations by sending the updated rank of list item ids. Use the /sync/recommendations method to get all list item ids.
OpenAPI snippet URL
GET /sync/recommendations/{type}/{sort}
Summary: Get personal recommendations
🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis
If the user only had 50 movies and TV shows to bring with them on a desert island, what would they be? These recommendations are used to enchance Trakt’s social recommendation algorithm. Apps should encourage user’s to build their personal recommendations so the algorithm keeps getting better.
Notes
Each recommendation contains a notes field explaining why the user recommended the item.
OpenAPI snippet URL
GET /sync/watched/{type}
Summary: Get watched
🔒 OAuth Required ✨ Extended Info
Returns all movies or shows a user has watched sorted by most plays.
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.
OpenAPI snippet URL
POST /sync/watchlist
Summary: Add items to watchlist
🔒 OAuth Required 😁 Emojis 🔥 VIP Enhanced
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 (255 maximum characters) field with custom text. The user must be a Trakt VIP to send notes.
Limits
If the user’s watchlist limit is exceeded, a 420 HTTP error code is returned. Use the /users/settings method to get all limits for a user account. In most cases, upgrading to Trakt 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. |
OpenAPI snippet URL
POST /sync/watchlist/remove
Summary: Remove items from watchlist
🔒 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. |
OpenAPI snippet URL
POST /sync/watchlist/reorder
Summary: Reorder watchlist items
🔒 OAuth Required
Reorder all items on a user’s watchlist by sending the updated rank of list item ids. Use the /sync/watchlist method to get all list item ids.
OpenAPI snippet URL
GET /sync/watchlist/{type}/{sort}
Summary: Get watchlist
🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis
Returns all items in a user’s watchlist filtered by type.
Notes
Each watchlist item contains a notes field with text entered by the user.
Sorting Headers
By default, all list items are sorted by rank asc. We send X-Applied-Sort-By and X-Applied-Sort-How headers to indicate how the results are actually being sorted.
We also send X-Sort-By and X-Sort-How headers which indicate the user’s sort preference. Use these to to custom sort the watchlist in your app for more advanced sort abilities we can’t do in the API. Values for X-Sort-By include rank, added, title, released, runtime, popularity, percentage, and votes. Values for X-Sort-How include asc and desc.
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.
The watchlist should not be used as a list of what the user is actively watching.
Use a combination of the /sync/watched and /shows/:id/progress methods to get what the user is actively watching.
OpenAPI snippet URL
GET /users/hidden/{section}
Summary: Get hidden items
🔒 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.
OpenAPI snippet URL
POST /users/hidden/{section}
Summary: Add hidden items
🔒 OAuth Required
Hide items for a specific section. Here’s what type of items can hidden for each section.
Hideable Media Objects
| Section | Objects |
|---|---|---|
| calendar | movie, show |
| progress_watched | show, season |
| progress_collected | show, season |
| recommendations | movie, show |
| comments | user |
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. |
OpenAPI snippet URL
POST /users/hidden/{section}/remove
Summary: Remove hidden items
🔒 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 |
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. |
OpenAPI snippet URL
GET /users/requests
Summary: Get follow requests
🔒 OAuth Required ✨ Extended Info
List a user’s pending follow requests so they can either approve or deny them.
OpenAPI snippet URL
GET /users/requests/following
Summary: Get pending following requests
🔒 OAuth Required ✨ Extended Info
List a user’s pending following requests that they’re waiting for the other user’s to approve.
OpenAPI snippet URL
DELETE /users/requests/{id}
Summary: Deny follow request
🔒 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.
OpenAPI snippet URL
POST /users/requests/{id}
Summary: Approve follow request
🔒 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.
OpenAPI snippet URL
GET /users/saved_filters/{section}
Summary: Get saved filters
🔒 OAuth Required 📄 Pagination 🔥 VIP Only
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.
OpenAPI snippet URL
GET /users/settings
Summary: Retrieve settings
🔒 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.
OpenAPI snippet URL
GET /users/{id}
Summary: Get user profile
🔓 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.
OpenAPI snippet URL
GET /users/{id}/collection/{type}
Summary: Get collection
🔓 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.
OpenAPI snippet URL
GET /users/{id}/comments/{comment_type}/{type}
Summary: Get comments
🔓 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.
OpenAPI snippet URL
DELETE /users/{id}/follow
Summary: Unfollow this user
🔒 OAuth Required
Unfollow someone you already follow.
OpenAPI snippet URL
POST /users/{id}/follow
Summary: Follow this user
🔒 OAuth Required
If the user has a private profile, the follow request will require approval (approved_at will be null). If a user is public, they will be followed immediately (approved_at will have a date).
Note: If this user is already being followed, a 409 HTTP status code will returned.
OpenAPI snippet URL
GET /users/{id}/followers
Summary: Get followers
🔓 OAuth Optional ✨ Extended Info
Returns all followers including when the relationship began.
OpenAPI snippet URL
GET /users/{id}/following
Summary: Get following
🔓 OAuth Optional ✨ Extended Info
Returns all user’s they follow including when the relationship began.
OpenAPI snippet URL
GET /users/{id}/friends
Summary: Get friends
🔓 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.
OpenAPI snippet URL
GET /users/{id}/history/{type}/{item_id}
Summary: Get watched history
🔓 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 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 |
OpenAPI snippet URL
GET /users/{id}/likes/{type}
Summary: Get likes
🔒 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.
Note: This returns a lot of data, so please only use this extended parameter if you actually need it!
OpenAPI snippet URL
GET /users/{id}/lists
Summary: Get a user’s personal lists
🔓 OAuth Optional 😁 Emojis
Returns all personal lists for a user. Use the /users/:id/lists/:list_id/items method to get the actual items a specific list contains.
OpenAPI snippet URL
POST /users/{id}/lists
Summary: Create personal list
🔒 OAuth Required 🔥 VIP Enhanced
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 method to get all limits for a user account. In most cases, upgrading to Trakt VIP will increase the limits.
JSON POST Data
| Key | Type | Default | Value |
|---|---|---|---|
name * | string | Name of the list. | |
description | string | Description for this list. | |
privacy | string | private | private, 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, percentage, votes, my_rating, random, watched, collected |
sort_how | string | asc | asc, desc |
OpenAPI snippet URL
GET /users/{id}/lists/collaborations
Summary: Get all lists a user can collaborate on
🔓 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.
OpenAPI snippet URL
POST /users/{id}/lists/reorder
Summary: Reorder a user’s lists
🔒 OAuth Required
Reorder all lists by sending the updated rank of list ids. Use the /users/:id/lists method to get all list ids.
OpenAPI snippet URL
DELETE /users/{id}/lists/{list_id}
Summary: Delete a user’s personal list
🔒 OAuth Required
Remove a personal list and all items it contains.
OpenAPI snippet URL
GET /users/{id}/lists/{list_id}
Summary: Get personal list
🔓 OAuth Optional 😁 Emojis
Returns a single personal list. Use the /users/:id/lists/:list_id/items method to get the actual items this list contains.
OpenAPI snippet URL
PUT /users/{id}/lists/{list_id}
Summary: Update personal list
🔒 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.
JSON POST Data
| Key | Type | Value |
|---|---|---|---|
| name | string | Name of the list. |
| description | string | Description for this list. |
| privacy | string | private, 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, percentage, votes, my_rating, random, watched, collected |
| sort_how | string | asc, desc |
OpenAPI snippet URL
GET /users/{id}/lists/{list_id}/comments/{sort}
Summary: Get all list comments
🔓 OAuth Optional 📄 Pagination 😁 Emojis
Returns all top level comments for a list. By default, the newest comments are returned first. Other sorting options include oldest, most likes, and most replies.
OpenAPI snippet URL
POST /users/{id}/lists/{list_id}/items
Summary: Add items to personal list
🔒 OAuth Required 😁 Emojis 🔥 VIP Enhanced
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 (255 maximum characters) field with custom text. The user must be a Trakt 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 method to get all limits for a user account. In most cases, upgrading to Trakt 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. |
OpenAPI snippet URL
POST /users/{id}/lists/{list_id}/items/remove
Summary: Remove items from personal list
🔒 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. |
OpenAPI snippet URL
POST /users/{id}/lists/{list_id}/items/reorder
Summary: Reorder items on a list
🔒 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 method to get all list item ids.
OpenAPI snippet URL
GET /users/{id}/lists/{list_id}/items/{type}
Summary: Get items on a personal list
🔓 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 Headers
All list items are sorted by ascending rank. We also send X-Sort-By and X-Sort-How headers which can be used to custom sort the list in your app based on the user’s preference. Values for X-Sort-By include rank, added, title, released, runtime, popularity, percentage, votes, my_rating, random, watched, and collected. Values for X-Sort-How include asc and desc.
OpenAPI snippet URL
DELETE /users/{id}/lists/{list_id}/like
Summary: Remove like on a list
🔒 OAuth Required
Remove a like on a list.
OpenAPI snippet URL
POST /users/{id}/lists/{list_id}/like
Summary: Like a list
🔒 OAuth Required
Votes help determine popular lists. Only one like is allowed per list per user.
OpenAPI snippet URL
GET /users/{id}/lists/{list_id}/likes
Summary: Get all users who liked a list
🔓 OAuth Optional 📄 Pagination
Returns all users who liked a list.
OpenAPI snippet URL
GET /users/{id}/ratings/{type}/{rating}
Summary: Get ratings
🔓 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.
OpenAPI snippet URL
GET /users/{id}/recommendations/{type}/{sort}
Summary: Get personal recommendations
🔒 OAuth Required 📄 Pagination Optional ✨ Extended Info 😁 Emojis
Returns the top 50 items a user personally recommendeds to others. These recommendations are used to enchance Trakt’s social recommendation algorithm. Apps should encourage user’s to build their personal recommendations so the algorithm keeps getting better.
Notes
Each recommendation contains a notes field explaining why the user recommended the item.
OpenAPI snippet URL
GET /users/{id}/stats
Summary: Get stats
🔓 OAuth Optional
Returns stats about the movies, shows, and episodes a user has watched, collected, and rated.
OpenAPI snippet URL
GET /users/{id}/watched/{type}
Summary: Get watched
🔓 OAuth Optional ✨ Extended Info
Returns all movies or shows a user has watched sorted by most plays.
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.
OpenAPI snippet URL
GET /users/{id}/watching
Summary: Get watching
🔓 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.
OpenAPI snippet URL
GET /users/{id}/watchlist/{type}/{sort}
Summary: Get watchlist
🔓 OAuth Optional 📄 Pagination Optional ✨ Extended Info 😁 Emojis
Returns all items in a user’s watchlist filtered by type.
Notes
Each watchlist item contains a notes field with text entered by the user.
Sorting Headers
By default, all list items are sorted by rank asc. We send X-Applied-Sort-By and X-Applied-Sort-How headers to indicate how the results are actually being sorted.
We also send X-Sort-By and X-Sort-How headers which indicate the user’s sort preference. Use these to to custom sort the watchlist in your app for more advanced sort abilities we can’t do in the API. Values for X-Sort-By include rank, added, title, released, runtime, popularity, percentage, and votes. Values for X-Sort-How include asc and desc.
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.
The watchlist should not be used as a list of what the user is actively watching.
Use a combination of the /sync/watched and /shows/:id/progress methods to get what the user is actively watching.
OpenAPI snippet URL