Trakt API

OpenAPI apis-guru

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 and sections for more info on what needs to be sent with each API call. Also check out the section insight into the features Trakt supports.

Create an App

To use the Trakt API, you'll need to .

Stay Connected

API discussion and bugs should be posted in the and watch the repository if you'd like to get notifications. Make sure to follow our and too.

API URL

The API should always be accessed over SSL.

If you would like to use our sandbox environment to not fill production with test data, use this URL over SSL. Note: Staging is a completely separate environment, so you'll need to .

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
`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 - have the user contact support
`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`
`trakt-api-key` *	Your `client_id` listed under your Trakt applications.
`trakt-api-version` *	`2`

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 instruct the user to so we can fix their account. API access will be suspended for the user until we fix their account.

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 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 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.

Note: This returns a lot of extra data, so please only use extended parameters if you actually need them!

Level	Description
`full`	Complete info for an item.
`metadata`	Collection only. Additional video and audio info.

Filters

Some movies, shows, calendars, and search 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.

Note: 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`
`languages`	✓	`en`
`countries`	✓	`us`
`runtimes`		`30-90`	Range in minutes.
`studios`	✓	`marvel-studios`	Studio slugs.

Rating Filters

Trakt, TMDB, and IMDB ratings apply to movies, shows, and episodes. Rotten Tomatoes and Metacritic apply to movies.

Parameter	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`	`5.5-10.0`	Rotten Tomatoes meter 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.
`networks`	✓	`HBO`	Network name.
`status`	✓	`ended`	Set to `returning series`, `continuing`, `in production`, `planned`, `upcoming`, `pilot`, `canceled`, or `ended`.

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 (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 short codes and it's up to your app to convert them 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

show

season

episode

person

user

Images

The standard media objects for all movie, show, season, episode, and person items include an ids object. These ids map to other services like , , , , and .

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.

Media	Type
`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/:slug`
`show`	`/shows/:slug`
`season`	`/shows/:slug/seasons/:num`
`episode`	`/shows/:slug/seasons/:num/episodes/:num`
`person`	`/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`
	`TraktSharp`
`C++`	`libtraqt`
`Clojure`	`clj-trakt`
`Java`	`trakt-java`
`Node.js`	`Trakt.tv`
	`TraktApi2`
`Python`	`trakt.py`
	`pyTrakt`
`R`	`tRakt`
`React Native`	`nodeless-trakt`
`Ruby`	`omniauth-trakt`
	`omniauth-trakt`
`Swift`	`TraktKit`
	`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.
`recommendations`	Movies and TV shows a user personally recommends to others.

Homepage: https://api.apis.guru/v2/specs/trakt.tv/1.0.0.json
Provider: trakt.tv
OpenAPI version: 3.0.0
Spec (JSON): https://api.apis.guru/v2/specs/trakt.tv/1.0.0/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/trakt.tv/1.0.0/openapi.yaml

Tools (185)

Extracted live via the executor SDK.

authenticationDevices.generateNewDeviceCodes

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.

Key	Type	Value
`client_id` *	string	Get this from your app settings.

authenticationDevices.pollForTheAccessToken

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*

authenticationOAuth.authorizeApplication

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 hostname when creating this URL and not the API URL.

authenticationOAuth.exchangeRefreshTokenForAccessToken

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`

authenticationOAuth.revokeAnAccessToken

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.
calendars.getCalendarsAllDvdStartDateDays

✨ Extended Info 🎚 Filters
Returns all movies with a DVD release date during the time period specified.
calendars.getCalendarsAllMoviesStartDateDays

✨ Extended Info 🎚 Filters
Returns all movies with a release date during the time period specified.
calendars.getCalendarsAllShowsNewStartDateDays

✨ Extended Info 🎚 Filters
Returns all new show premieres (season 1, episode 1) airing during the time period specified.
calendars.getCalendarsAllShowsPremieresStartDateDays

✨ Extended Info 🎚 Filters
Returns all show premieres (any season, episode 1) airing during the time period specified.
calendars.getCalendarsAllShowsStartDateDays

✨ Extended Info 🎚 Filters
Returns all shows airing during the time period specified.
calendars.getDvdReleases

🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all movies with a DVD release date during the time period specified.
calendars.getMovies

🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all movies with a release date during the time period specified.
calendars.getNewShows

🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all new show premieres (season 1, episode 1) airing during the time period specified.
calendars.getSeasonPremieres

🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all show premieres (any season, episode 1) airing during the time period specified.
calendars.getShows

🔒 OAuth Required ✨ Extended Info 🎚 Filters
Returns all shows airing during the time period specified.
certifications.getCertifications

Get a list of all certifications, including names, slugs, and descriptions.

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.

checkin.checkIntoAnItem

🔒 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 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.*

checkin.deleteAnyActiveCheckins

🔒 OAuth Required
Removes any active checkins, no need to provide a specific item.
comments.deleteACommentOrReply

🔒 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.
comments.getACommentOrReply

😁 Emojis
Returns a single comment and indicates how many replies it has. Use to get the actual replies.
comments.getAllUsersWhoLikedAComment

📄 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.
comments.getRecentlyCreatedComments

📄 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.
comments.getRecentlyUpdatedComments

📄 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.
comments.getRepliesForAComment

📄 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 again with the new comment id.
comments.getTheAttachedMediaItem

✨ 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.
comments.getTrendingComments

📄 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.
comments.likeAComment

🔒 OAuth Required
Votes help determine popular comments. Only one like is allowed per comment per user.

comments.postAComment

🔒 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

comments.postAReplyForAComment

🔒 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?
comments.removeLikeOnAComment

🔒 OAuth Required
Remove a like on a comment.
comments.updateACommentOrReply

🔒 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?
countries.getCountries

Get a list of all countries, including names and codes.
episodes.getAllEpisodeComments

📄 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.
episodes.getAllEpisodeTranslations

Returns all translations for an episode, including language and translated values for title and overview.
episodes.getAllPeopleForAnEpisode

✨ 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!
episodes.getASingleEpisodeForAShow

✨ 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.
episodes.getEpisodeRatings

Returns rating (between 0 and 10) and distribution for an episode.
episodes.getEpisodeStats

Returns lots of episode stats.
episodes.getListsContainingThisEpisode

📄 Pagination 😁 Emojis
Returns all lists that contain this episode. By default, personal lists are returned sorted by the most popular.
episodes.getShowsIdSeasonsSeasonEpisodesEpisodeWatching

✨ Extended Info
Returns all users watching this episode right now.
genres.getGenres

Get a list of all genres, including names and slugs.
languages.getLanguages

Get a list of all langauges, including names and codes.
lists.getAllListComments

📄 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.
lists.getAllUsersWhoLikedAList

📄 Pagination
Returns all users who liked a list.
lists.getItemsOnAList

📄 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.
lists.getList

😁 Emojis
Returns a single list. Use the method to get the actual items this list contains.
Note: You must use an integer id, and only public lists will return data.
lists.getPopularLists

📄 Pagination 😁 Emojis
Returns the most popular lists. Popularity is calculated using total number of likes and comments.
lists.getTrendingLists

📄 Pagination 😁 Emojis
Returns all lists with the most likes and comments over the last 7 days.
movies.getAllMovieAliases

Returns all title aliases for a movie. Includes country where name is different.
movies.getAllMovieComments

📄 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.
movies.getAllMovieReleases

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 .
movies.getAllMovieTranslations

Returns all translations for a movie, including language and translated values for title, tagline and overview.
movies.getAllPeopleForAMovie

✨ 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.
movies.getAMovie

✨ 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.
movies.getListsContainingThisMovie

📄 Pagination 😁 Emojis
Returns all lists that contain this movie. By default, personal lists are returned sorted by the most popular.
movies.getMovieRatings

Returns rating (between 0 and 10) and distribution for a movie.
movies.getMovieStats

Returns lots of movie stats.
movies.getMovieStudios

Returns all studios for a movie.
movies.getPopularMovies

📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most popular movies. Popularity is calculated using the rating percentage and the number of ratings.
movies.getRecentlyUpdatedMovies

📄 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.
movies.getRecentlyUpdatedMovieTraktIDs

📄 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.
movies.getRelatedMovies

📄 Pagination ✨ Extended Info
Returns related and similar movies.
movies.getTheMostAnticipatedMovies

📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most anticipated movies based on the number of lists a movie appears on.
movies.getTheMostCollectedMovies

📄 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.
movies.getTheMostPlayedMovies

📄 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.
movies.getTheMostRecommendedMovies

📄 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.
movies.getTheMostWatchedMovies

📄 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.
movies.getTheWeekendBoxOffice

✨ Extended Info
Returns the top 10 grossing movies in the U.S. box office last weekend. Updated every Monday morning.
movies.getTrendingMovies

📄 Pagination ✨ Extended Info 🎚 Filters
Returns all movies being watched right now. Movies with the most users are returned first.
movies.getUsersWatchingRightNow

✨ Extended Info
Returns all users watching this movie right now.
networks.getNetworks

Get a list of all TV networks, including the name.
people.getASinglePerson

✨ 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.
people.getListsContainingThisPerson

📄 Pagination 😁 Emojis
Returns all lists that contain this person. By default, personal lists are returned sorted by the most popular.
people.getMovieCredits

✨ 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.
people.getRecentlyUpdatedPeople

📄 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.
people.getRecentlyUpdatedPeopleTraktIDs

📄 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.
people.getShowCredits

✨ 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.
recommendations.getMovieRecommendations

🔒 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.
recommendations.getShowRecommendations

🔒 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.
recommendations.hideAMovieRecommendation

🔒 OAuth Required
Hide a movie from getting recommended anymore.
recommendations.hideAShowRecommendation

🔒 OAuth Required
Hide a show from getting recommended anymore.
scrobble.pauseWatchingInAMediaCenter

🔒 OAuth Required
Use this method when the video is paused. The playback progress will be saved and can be used to resume the video from this exact position. Unpause a video by calling the 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.
scrobble.startWatchingInAMediaCenter

🔒 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.
scrobble.stopOrFinishWatchingInAMediaCenter

🔒 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 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 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.

Key	Type
`twitter`	boolean
`tumblr`	boolean
`medium`	boolean

Key	Type	Default	Value
`comment` *	string		Text for the reply.
`spoiler`	boolean	`false`	Is this a spoiler?

Key	Type	Default	Value
`comment`	string		Text for the comment.
`spoiler`	boolean	`false`	Is this a spoiler?

search.getIdLookupResults

📄 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`

search.getTextQueryResults

📄 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
seasons.getAllPeopleForASeason

✨ 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!
seasons.getAllSeasonComments

📄 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.
seasons.getAllSeasonsForAShow

✨ 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!
seasons.getAllSeasonTranslations

Returns all translations for an season, including language and translated values for title and overview.
seasons.getListsContainingThisSeason

📄 Pagination 😁 Emojis
Returns all lists that contain this season. By default, personal lists are returned sorted by the most popular.
seasons.getSeasonRatings

Returns rating (between 0 and 10) and distribution for a season.
seasons.getSeasonStats

Returns lots of season stats.
seasons.getShowsIdSeasonsSeasonWatching

✨ Extended Info
Returns all users watching this season right now.
seasons.getSingleSeasonForAShow

✨ 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!
shows.getAllPeopleForAShow

✨ 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!
shows.getAllShowAliases

Returns all title aliases for a show. Includes country where name is different.
shows.getAllShowCertifications

Returns all content certifications for a show, including the country.
shows.getAllShowComments

📄 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.
shows.getAllShowTranslations

Returns all translations for a show, including language and translated values for title and overview.
shows.getASingleShow

✨ 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.
shows.getLastEpisode

✨ Extended Info
Returns the most recently aired episode. If no episode is found, a 204 HTTP status code will be returned.
shows.getListsContainingThisShow

📄 Pagination 😁 Emojis
Returns all lists that contain this show. By default, personal lists are returned sorted by the most popular.
shows.getNextEpisode

✨ Extended Info
Returns the next scheduled to air episode. If no episode is found, a 204 HTTP status code will be returned.
shows.getPopularShows

📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most popular shows. Popularity is calculated using the rating percentage and the number of ratings.
shows.getRecentlyUpdatedShows

📄 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.
shows.getRecentlyUpdatedShowTraktIDs

📄 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.
shows.getRelatedShows

📄 Pagination ✨ Extended Info
Returns related and similar shows.
shows.getShowCollectionProgress

🔒 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.
shows.getShowRatings

Returns rating (between 0 and 10) and distribution for a show.
shows.getShowsIdWatching

✨ Extended Info
Returns all users watching this show right now.
shows.getShowStats

Returns lots of show stats.
shows.getShowStudios

Returns all studios for a show.
shows.getShowWatchedProgress

🔒 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.
shows.getTheMostAnticipatedShows

📄 Pagination ✨ Extended Info 🎚 Filters
Returns the most anticipated shows based on the number of lists a show appears on.
shows.getTheMostCollectedShows

📄 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.
shows.getTheMostPlayedShows

📄 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.
shows.getTheMostRecommendedShows

📄 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.
shows.getTheMostWatchedShows

📄 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.
shows.getTrendingShows

📄 Pagination ✨ Extended Info 🎚 Filters
Returns all shows being watched right now. Shows with the most users are returned first.
shows.resetShowProgress

🔒 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.
shows.undoResetShowProgress

🔒 OAuth Required 🔥 VIP Only
Undo the reset and have watched progress use all watched history for the show.

Type	Field
`movie`	`title`
	`tagline`
	`overview`
	`people`
	`translations`
	`aliases`
`show`	`title`
	`overview`
	`people`
	`translations`
	`aliases`
`episode`	`title`
	`overview`
`person`	`name`
	`biography`
`list`	`name`
	`description`

sync.addItemsToCollection

🔒 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

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.

sync.addItemsToPersonalRecommendations

🔒 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.

sync.addItemsToWatchedHistory

🔒 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

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).

sync.addItemsToWatchlist

🔒 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 to send notes.
Limits
If the user's watchlist limit is exceeded, a 420 HTTP error code is returned. Use the method to get all limits for a user account. In most cases, upgrading to 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.
sync.addNewRatings

🔒 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.
sync.getCollection

🔒 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.
sync.getLastActivity

🔒 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.
sync.getPersonalRecommendations

🔒 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.
sync.getPlaybackProgress

🔒 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.
sync.getRatings

🔒 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.
sync.getWatched

🔒 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.

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.

sync.getWatchedHistory

🔒 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 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

sync.getWatchlist

🔒 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 and methods to get what the user is actively watching.
sync.removeAPlaybackItem

🔒 OAuth Required
Remove a playback item from a user's playback progress list. A 404 will be returned if the id is invalid.
sync.removeItemsFromCollection

🔒 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.
sync.removeItemsFromHistory

🔒 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 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.
sync.removeItemsFromPersonalRecommendations

🔒 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.
sync.removeItemsFromWatchlist

🔒 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.
sync.removeRatings

🔒 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.
sync.reorderPersonallyRecommendedItems

🔒 OAuth Required
Reorder all items on a user's personal recommendations by sending the updated rank of list item ids. Use the method to get all list item ids.
sync.reorderWatchlistItems

🔒 OAuth Required
Reorder all items on a user's watchlist by sending the updated rank of list item ids. Use the method to get all list item ids.
users.addHiddenItems

🔒 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.

users.addItemsToPersonalList

🔒 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 to send notes.

Limits

If the user's list item limit is exceeded, a 420 HTTP error code is returned. Use the method to get all limits for a user account. In most cases, upgrading to 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.

users.approveFollowRequest

🔒 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.

users.createPersonalList

🔒 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 method to get all limits for a user account. In most cases, upgrading to 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`

users.deleteAUserSPersonalList

🔒 OAuth Required
Remove a personal list and all items it contains.
users.denyFollowRequest

🔒 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.
users.followThisUser

🔒 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.
users.getAllListsAUserCanCollaborateOn

🔓 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.
users.getAUserSPersonalLists

🔓 OAuth Optional 😁 Emojis
Returns all personal lists for a user. Use the method to get the actual items a specific list contains.
users.getComments

🔓 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.
users.getFollowers

🔓 OAuth Optional ✨ Extended Info
Returns all followers including when the relationship began.
users.getFollowing

🔓 OAuth Optional ✨ Extended Info
Returns all user's they follow including when the relationship began.
users.getFollowRequests

🔒 OAuth Required ✨ Extended Info
List a user's pending follow requests so they can either approve or deny them.
users.getFriends

🔓 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.
users.getHiddenItems

🔒 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.
users.getItemsOnAPersonalList

🔓 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.
users.getLikes

🔒 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!
users.getPendingFollowingRequests

🔒 OAuth Required ✨ Extended Info
List a user's pending following requests that they're waiting for the other user's to approve.
users.getPersonalList

🔓 OAuth Optional 😁 Emojis
Returns a single personal list. Use the method to get the actual items this list contains.
users.getSavedFilters

🔒 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.
users.getStats

🔓 OAuth Optional
Returns stats about the movies, shows, and episodes a user has watched, collected, and rated.
users.getUserProfile

🔓 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.
users.getUsersIdCollectionType

🔓 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.

users.getUsersIdHistoryTypeItemId

🔓 OAuth Optional 📄 Pagination ✨ Extended Info

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

users.getUsersIdListsListIdCommentsSort

🔓 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.
users.getUsersIdListsListIdLikes

🔓 OAuth Optional 📄 Pagination
Returns all users who liked a list.
users.getUsersIdRatingsTypeRating

🔓 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.
users.getUsersIdRecommendationsTypeSort

🔒 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.
users.getUsersIdWatchedType

🔓 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.
users.getUsersIdWatchlistTypeSort

🔓 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 and methods to get what the user is actively watching.
users.getWatching

🔓 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.
users.likeAList

🔒 OAuth Required
Votes help determine popular lists. Only one like is allowed per list per user.
users.removeHiddenItems

🔒 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.

users.removeItemsFromPersonalList

🔒 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.

users.removeLikeOnAList

🔒 OAuth Required
Remove a like on a list.
users.reorderAUserSLists

🔒 OAuth Required
Reorder all lists by sending the updated rank of list ids. Use the method to get all list ids.
users.reorderItemsOnAList

🔒 OAuth Required
Reorder all items on a list by sending the updated rank of list item ids. Use the method to get all list item ids.
users.retrieveSettings

🔒 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.
users.unfollowThisUser

🔒 OAuth Required
Unfollow someone you already follow.
users.updatePersonalList

🔒 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.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools

Create an App

Stay Connected

API URL

Verbs

Status Codes

Required Headers

Rate Limiting

Locked User Account

VIP Methods

Pagination

Extended Info

Filters

Common Filters

Rating Filters

Movie Filters

Show Filters

CORS

Dates

Emojis

Standard Media Objects

movie

show

season

episode

person

user

Images

Website Media Links

Third Party Libraries

Terminology

Tools (185)

JSON POST Data

JSON POST Data

Status Codes

JSON POST Data

JSON POST Data

✨ Extended Info 🎚 Filters

✨ Extended Info 🎚 Filters

✨ Extended Info 🎚 Filters

✨ Extended Info 🎚 Filters

✨ Extended Info 🎚 Filters

🔒 OAuth Required ✨ Extended Info 🎚 Filters

🔒 OAuth Required ✨ Extended Info 🎚 Filters

🔒 OAuth Required ✨ Extended Info 🎚 Filters

🔒 OAuth Required ✨ Extended Info 🎚 Filters

🔒 OAuth Required ✨ Extended Info 🎚 Filters

🔒 OAuth Required

JSON POST Data

Sharing

🔒 OAuth Required

🔒 OAuth Required

😁 Emojis

📄 Pagination

📄 Pagination ✨ Extended Info 😁 Emojis

📄 Pagination ✨ Extended Info 😁 Emojis

📄 Pagination 😁 Emojis

✨ Extended Info

📄 Pagination ✨ Extended Info 😁 Emojis

🔒 OAuth Required

🔒 OAuth Required 😁 Emojis

JSON POST Data

Sharing

🔒 OAuth Required 😁 Emojis

JSON POST Data

🔒 OAuth Required

🔒 OAuth Required 😁 Emojis

JSON POST Data

📄 Pagination 😁 Emojis

✨ Extended Info

Guest Stars

✨ Extended Info

📄 Pagination 😁 Emojis

✨ Extended Info

📄 Pagination 😁 Emojis

📄 Pagination

📄 Pagination Optional ✨ Extended Info 😁 Emojis

Notes

Sorting Headers

😁 Emojis

📄 Pagination 😁 Emojis