Trakt API

At Trakt, we collect lots of interesting information about what tv shows and movies everyone is watching. Part of the fun with such data is making it available for anyone to mash up and use on their own site or app. The Trakt API was made just for this purpose. It is very easy to use, you basically call a URL and get some JSON back.

More complex API calls (such as adding a movie or show to your collection) involve sending us data. These are still easy to use, you simply POST some JSON data to a specific URL.

Make sure to check out the Required Headers and Authentication sections for more info on what needs to be sent with each API call. Also check out the Terminology section insight into the features Trakt supports.

Create an App

To use the Trakt API, you'll need to create a new API app.

Stay Connected

API discussion and bugs should be posted in the GitHub Developer Forum and watch the repository if you'd like to get notifications. Make sure to follow our API Blog and @traktapi on Twitter too.

API URL

The API should always be accessed over SSL.

https://api.trakt.tv

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

https://api-staging.trakt.tv

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 contact Trakt support 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 Trakt VIP in order to use this method. In your app, please open a browser to X-Upgrade-URL so the user can sign up for Trakt VIP.

Header	Value
X-Upgrade-URL	https://trakt.tv/vip

Some API methods are tagged 🔥 VIP Enhanced. A 420 HTTP status code is returned when the user has exceeded their account limit. Signing up for Trakt VIP 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	Genre slugs.
languages	✓	en	2 character language code.
countries	✓	us	2 character country code.
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	Multiples	Example	Value
ratings		75-100	Trakt rating range between 0 and 100.
votes		5000-10000	Trakt vote count between 0 and 100000.
tmdb_ratings		5.5-10.0	TMDB rating range between 0.0 and 10.0.
tmdb_votes		5000-10000	TMDB vote count between 0 and 100000.
imdb_ratings		5.5-10.0	IMDB rating range between 0.0 and 10.0.
imdb_votes		5000-10000	IMDB vote count between 0 and 3000000.
rt_meters		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 JoyPixels (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

{
    "title": "Batman Begins",
    "year": 2005,
    "ids": {
        "trakt": 1,
        "slug": "batman-begins-2005",
        "imdb": "tt0372784",
        "tmdb": 272
    }
}

show

{
    "title": "Breaking Bad",
    "year": 2008,
    "ids": {
        "trakt": 1,
        "slug": "breaking-bad",
        "tvdb": 81189,
        "imdb": "tt0903747",
        "tmdb": 1396
    }
}

season

{
    "number": 0,
    "ids": {
        "trakt": 1,
        "tvdb": 439371,
        "tmdb": 3577
    }
}

episode

{
    "season": 1,
    "number": 1,
    "title": "Pilot",
    "ids": {
        "trakt": 16,
        "tvdb": 349232,
        "imdb": "tt0959621",
        "tmdb": 62085
    }
}

person

{
    "name": "Bryan Cranston",
    "ids": {
        "trakt": 142,
        "slug": "bryan-cranston",
        "imdb": "nm0186505",
        "tmdb": 17419
    }
}

user

{
    "username": "sean",
    "private": false,
    "name": "Sean Rudford",
    "vip": true,
    "vip_ep": true,
    "ids": {
        "slug": "sean"
    }
}

Images

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

Most of these services have free APIs you can use to grab lots of great looking images. Here’s a chart to help you find the best artwork for your app. We also wrote an article to help with this.

Media	Type	TMDB	TVDB	Fanart.tv	OMDB
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	https://github.com/henrikfroehling/Trakt.NET
	TraktSharp	https://github.com/wwarby/TraktSharp
C++	libtraqt	https://github.com/RobertMe/libtraqt
Clojure	clj-trakt	https://github.com/niamu/clj-trakt
Java	trakt-java	https://github.com/UweTrottmann/trakt-java
Node.js	Trakt.tv	https://github.com/vankasteelj/trakt.tv
	TraktApi2	https://github.com/PatrickE94/traktapi2
Python	trakt.py	https://github.com/fuzeman/trakt.py
	pyTrakt	https://github.com/moogar0880/PyTrakt
R	tRakt	https://github.com/jemus42/tRakt
React Native	nodeless-trakt	https://github.com/kdemoya/nodeless-trakt
Ruby	omniauth-trakt	https://github.com/wafcio/omniauth-trakt
	omniauth-trakt	https://github.com/alextakitani/omniauth-trakt
Swift	TraktKit	https://github.com/MaxHasADHD/TraktKit
	AKTrakt	https://github.com/arsonik/AKTrakt

Terminology

Trakt has a lot of features and here's a chart to help explain the differences between some of them.

Term	Description
scrobble	Automatic way to track what a user is watching in a media center.
checkin	Manual action used by mobile apps allowing the user to indicate what they are watching right now.
history	All watched items (scrobbles, checkins, watched) for a user.
collection	Items a user has available to watch including Blu-Rays, DVDs, and digital downloads.
watchlist	Items a user wants to watch in the future. Once watched, they are auto removed from this list.
list	Personal list for any purpose. Items are not auto removed from any personal lists.
recommendations	Movies and TV shows a user personally recommends to others.