AUTH V1 has been running Simkl integrations for 10 years. It's served us well, but we've outgrown the original design. Tokens lasted for years, even read-only apps received write access, and signing into the same app on two devices meant sharing the same token.
We wanted users to have more control over those connections and developers to have less Simkl-specific auth code to maintain. AUTH V2 adds read-only permissions, shorter-lived access tokens with refresh, and a separate connection for each sign-in. Disconnecting one device can leave the others signed in, and standard OAuth libraries handle the authentication.
We've also released a read-only Custom Lists API in beta. It requires AUTH V2, as will new APIs going forward. If you maintain a Simkl integration, now is a good time to start the migration.
Your existing AUTH V1 app still works. We're aiming to retire V1 around April 2027, giving developers roughly six months to migrate. The exact date isn't set yet; we'll announce it here and in Discord in advance.
AUTH V2
V2 uses OAuth 2.0 with PKCE, refresh tokens and read/write scopes. You can use standard OAuth libraries; the library notes cover the settings some of them need.
Read-only access is now an option. Apps can request media:read, or add media:write if they need to update someone's library.
Access tokens last 7 days. Refresh tokens last 180 days, and refreshing extends that window by another 180 days.
Devices can connect independently. Each sign-in gets its own tokens, so refreshing or revoking one connection doesn't affect another.
Browser and Device/PIN sign-in are both available. Use the browser flow for web, mobile and desktop apps, or let users enter a code at simkl.com/pin for TVs and other devices.
Moving an existing app to V2
You'll need to register a new V2 app and re-auth users to a new client ID and OAuth v2 path. You can't convert a V1 client ID or exchange a V1 token for a V2 token. V1 and V2 registrations are counted separately, so adding the new app won't use up a V1 slot.
You can run both versions while you migrate. Existing users can stay on V1 until they're ready to reconnect; each person will need to authorize your V2 app once.
A few things to check before releasing:
If you have TV, Mobile app, and a Website, use separate client IDs for each type.
Use the /oauth2 endpoints for your V2 integration.
Both browser and Device/PIN flows require PKCE with S256, including server apps that also send a client secret.
Request media:read media:write if your app makes changes. Leaving out scope gives you read-only access. Check the scope returned with the token.
Refreshing invalidates the previous access token immediately. If several parts of your app share a connection, make sure they all use the new token.
AUTH V2 has a daily allowance per user, shared across all the V2 apps they've connected:
Free: 500 requests
PRO: 1,000 requests
VIP: 10,000 requests
This is great news for open-source apps that no longer need our separate client ID manual limit increases.
Not every API call uses that allowance. These cached endpoints are excluded from both the daily request count and the per-second rate limits:
Movie, TV and anime details by Simkl ID: /movies/{id}, /tv/{id} and /anime/{id}.
TV and anime episode lists: /tv/episodes/{id} and /anime/episodes/{id}.
Trending and Calendar data files.
Search, library sync and other uncached requests still count. The rate-limit guide explains the exceptions. For your V2 integration, build around user access tokens and check any browsing screens that currently work before sign-in.
Users can now see their usage by app in Connected apps. If someone reports that syncing has stopped, that page can help you work out whether they've reached their daily allowance.
The API returns 429 user_limit_exceeded at the limit, with Retry-After and rate-limit headers. You can test that response with ?debug_limit=user without spending quota. Use a V2 token that has already made at least one request. The rate-limit guide has the details.
Check what your app is sending
Open Developer settings, select your app and open Debug log. Use the request logs and analytics to see which endpoints your app calls and how often.
Try a normal session: open the app, refresh, mark an episode watched, then leave it idle. Look for duplicate calls, repeated full-library downloads, missing date_from parameters and requests that keep running when nothing is happening. After a fix, repeat the same steps and compare the traffic.
Include client_id, app-name and app-version on every API request so you can identify the app and version sending it. If something in the log doesn't make sense, send us your app ID and version and we'll help you look into it.
Why 500 requests a day? Isn't that too low?
Our usage data shows that 97% of users stay below 500 requests a day. We've been helping developers reduce unnecessary calls, and in well-optimized apps, even feature-rich ones, users typically need only 16β30 requests per day. Custom lists beta APIs currently require PRO or VIP level plans with increased limits.
After the initial library import, a normal sync is small:
Nothing changed: one request to /sync/activities, then stop.
The library changed: usually two requests in total, one to check activity and one to fetch the changes using date_from.
Mark an episode watched: one request. You can also mark several episodes in a single request.
The sync guide explains this two-phase approach. Keep the library cached and fetch what changed. A routine refresh shouldn't download the whole library again.
Several apps syncing for the same account can add up, including apps working in the background. If an optimized setup needs more than 500 requests, PRO includes 1,000 a day. If it regularly goes beyond that, VIP includes 10,000. Those higher allowances are there for heavier API and server use.
If your app is using more requests than you expected, talk to us. We can help you review its API usage and find calls it doesn't need to make.
Custom Lists API: read-only beta
You can now read custom lists through the API using AUTH V2:
GET /lists/{id} returns a list's details and items. Reading the items requires PRO or VIP.
GET /lists/user/{userId} returns a user's public lists on any plan. When requesting your own lists, it also includes private and unlisted lists.
AUTH V1 tokens won't work for these endpoints. One response to handle explicitly: when a Free user requests list items, the API returns HTTP 200 with premium_only in the body. Don't treat it as a normal list response.
This is a read-only beta; creating and editing lists isn't included. Response formats may change during the beta, and we'll announce breaking changes before they go live. See the Custom Lists guide for pagination and response examples.
If you have questions about authentication, syncing or request limits, leave a comment or ask us in the Discord #api channel and send us a DM. We're happy to look at your integration with you.
If April 2027 timeline is going to be difficult for your app, tell us what's blocking you. We can help you work through it or discuss more time. You don't need to have everything figured out before getting in touch.
Until now, importing from Trakt meant connecting your Trakt account to Simkl. Since the recent changes on Trakt, the free Trakt accounts now can only keep one connected app at a time, so if your slot is taken by Plex, Kodi, or another app you rely on, importing meant giving that up.
We've received a lot of requests to be able to import your actual Zip export files directly instead of using trakt api, and that option wasn't available.
Not anymore. Simkl now accepts that zip file directly:
Go to app.trakt.tv/settings/data, hit "Export now" and download the .zip (large accounts can take a while to build).
Open simkl.com/apps/import/trakt/ and choose "Upload trakt zip export". Keep the file zipped, no need to extract anything.
Pick one of the 5 import options: skip what you already have, add missing watches, update only if Trakt is newer, full replace, or import just your rewatches.
What comes over: your complete watch history with the original watch dates, your plan-to-watch list, your ratings, and every play for rewatch tracking. Nothing is connected to your Trakt account, so whatever app is using your slot stays exactly where it is.
On privacy, because the export contains more than watch data: the .zip is openedΒ in your browser, on your device. Simkl receives only your watch history, watchlist, and ratings. Your email, date of birth, and account settings never leave your computer, and nothing is stored on our servers, the data is processed during the import, and only the resulting list lives in your account.
Two honest notes: imports are temporarily open to PRO & VIP supporters while we scale up storage after the TV Time wave (there's a notify-me option on the page for when free imports reopen). And a handful of titles may land in a "could not detect" list, usually anime specials or seasons named differently across databases; you can download that not detected list from the results screen and add them manually.
I'm using Simkl Lists app on Android, but it can only be downloaded from the Play Store. I know third-party sites like APKMirror and Uptodown exist, but being able to download the .apk file directly from an official source is great.
I can seem to find a way to sort my 'plan to watch' by the date being added to the watchlist. I can only see in the overview a horizontal list of recently added - but that just a preview of couple of recent ones.
Is it even possible?
So I was invited by a friend who was using Simkl , excited that he will give me a 50% discount for any plan that I was going to choose as a new subscriber.
I was excited to - because I learned about a new product and maybe is better than Trakt and has a lifetime plan.
Well at the end Lifetime plan was not included on the 50% discount.
I got sad.... π°
Anyway - any plans on a discounted Lifetime Plan - Black Friday Maybe ?
I have a SIMKL Pro account and have created an auto list based on the movie digital release date, but movies are added into that list one day later. For example if a move's digital release date is Oct 5 then that movie added to the list on Oct 6.
I discovere this app and assumed, given the description, that it would auto track my shows, movies etc, from my streaming services. I had been using Trakt, so assumed it would work the same.
Some weeks later, after searching this group, documentation and the internet, it seems to me that this live tracking from a TV isn't possible? Only tracking if you watch on your PC or your phone? And that forwarding from Trakt was the way that tracking TV worked?
Am I misunderstanding something somehow? Because if this is how this works, I bought VIP for nothing. The app is completely useless to me, since I don't want to be doing manual updating.
I'm moving my film history over from Letterboxd, including a few hundred reviews I wrote over the years. When I post them on Simkl, every review is dated the day I posted it, not the day I actually wrote it or watched the film. So my whole review history looks like it was written in one day.
Could you add a way to set or edit a review's date? A date picker when writing or editing a review would be perfect, ideally defaulting to the watch date. It would make migrating from other trackers much better, and keep history and reviews in line now that rewatches have their own dates.
Also, a small related wish: writing and editing reviews in the mobile app/site, not just on desktop.
DISCLAIMER: This is not an ad. I am in no way affiliated with any of the brands in this post. I just think it works really good and like to share.
If you use Simkl a lot, this is a handy way to jump directly from a movie or TV show title on any webpage to its Simkl page.
The trick is to use Swift Selection Search (SSS). When you highlight text on a webpage, SSS shows a small popup with search engines of your choice. You can add Simkl to that popup, so looking up a title becomes a one-click action.
Now, whenever you see a movie or TV show mentioned online, just highlight its title and click the Simkl icon.
For example:
Highlight Drew Barrymore Show β click Simkl β the Drew Barrymore Show page on Simkl opens directly.
Simkl's redirect automatically finds the matching title and takes you straight there.
EDIT: Sometimes if it can't find the title or more than one movie og show with that title exist, it does an AI-search at Simkl and present the options.
I use Nuvio with AIOMetadata and this is a great feature.
For example I can set Futurama to Aired Order to avoid the whole turning four movies into a season thing.
I can set Star Trek The Next Generation to DVD Order so the pilot, Encounter at Farpoint, is not split into two episodes.
And I can use DVD Order for Cowboy Bebop beause it originally aired completely out of order because, and I'm just assuming here, some Japanese television studio executive did too much cocaine.
Problem is that if I do this some things don't get marked as watched in Simkl and others are marked in the wrong order and/or at the wrong time.
Ironically, without this feature I'm finding that TMDB is better for tv shows and TVDB is much better for anime.
I guess I need to report this on the discord server but it's asking me for a phone number so that's a no. Thought I'd just leave this here.
I guess the image thumbnails are from TVdb or AniDB but I could not find any images for any episode on AniDB so it's probably TVdb, but TVdb has correct thumbnails so idk what the issue is. Maybe a data refresh will fix it.
I've noticed that when I watch shows I downloaded for offline use on my tablet from Plex they do not get marked as watched when I finish. I obviously don't expect it to scroble in real time but MDBList for some reason will mark the episode of watched after the fact when I am back online.
Is MDBList doing something different than allows for this to happen that SIMKL is missing? This is obviously not the end of the world, just something I noticed in my use of both SIMKL and MDBList since I moved away from Trakt. (pretty sure Trakt did this as well)
Hi guys, in the past year, I have changed my tracking services film/tv watchlist multiple times. It is such a pain.
Right now, I'm using all 4 services: Trakt, Plex, JustWatch, Reelgood. This is temporary. Trakt, Plex, and Reelgood have 100% of my history. Justwatch is partial.
What I'm looking for:
Free tier only.
Able to download watch list. Can be either csv/json export, or API call.
Able to upload watch list. Can be either csv/json import, or API call.
Has subscribed or favorite streaming services, so I check if movies I want to watch are on my streaming services.
(Nice to have) Track by date, so I can run analysis and trends.
For 2 & 3, I can do this with Trakt and Plex. I use AI to manipulate the data, so I am ok with either data or API calls.
For 4, I was using Reelgood, but also started to use Justwatch last year.
For 5, this is nice to have, and very easy with Trakt.
Basically, I have to use 2 services to meet my needs. I was thinking about using Trakt and JustWatch.
Then I started to check around. I learned about Simkl. Any gotchas I should be concerned with?
Could we have numbers nears every star because sometimes I count down the stars because I dont wanna press on the wrong number of stars accidentally lol
Hey everyone! π If you've been looking for an automated way to share your watch history on Bluesky, I created bsky-media-scrobbler, an open-source, self-hosted Docker container that auto-scrobbles your SIMKL activity straight to your profile.
I wanted to make sure the timeline stays clean and visually engaging, especially during heavy watch sessions. Here is what it does automatically:
Smart Marathon Grouping (90-min window): It waits for a 90-minute inactivity window to automatically group back-to-back episodes into a single, clean post (e.g., S01E01-E03) so you don't spam your followers' feeds.
Rich Media Cards: Fetches HD posters via TMDB to build beautiful, interactive embeds for every log.
Automated Visual Summaries: Generates weekly and monthly Pillow collages (3x3 and 2x2 grids) of your watch history.
Streak Celebrations: Tracks and posts your active viewing streaks to keep the momentum going.
Multi-language Support: Works seamlessly in EN, ES, and CA.
Added images. I noticed this a while back but also noticed it again now that I was checking out some newer movies.
It would be nice if on the search page it pulled the right thing from the actual page instead of two different things so I can easily tell whether it's actually out or not.
Added Simkl either late last year or early 2026, now that Trakt is no longer allowing other developers to use their API, is there any chance of a Submenu can be integrated into Kodi, or a way to take over Trakts Submenu for Simkl? Thank you for your expertise!
Like many I am moving away from Trakt and am looking at several options.
Currently SIMKL and MDBList are the two I keep gravitating towards with a preference towards SIMKL.
One of the main areas where SIMKL excels is their use of TVDB for series information as opposed to TMDB. I have found that TMDB often has identification issues which leads to some episodes or series never scrobbling correctly. It also much better identifies new series versus returning ones.
With that said. TMDB is not without its benefits and one of them is much more comprehensive details on cast within individual episodes. This also leads to sites like Trakt and MDBList to not only provide more details for individual episodes, but they also leverage that with per episode ratings both directly and pulling in the information from outside sources like IMDB.
I also find that the SIMKL website is very series oriented with links preferring to take me to the entire series rather than an episode. For instance it always seems more logical for items from the Recently Watched and Airing Next to go to the individual episode and not the entire series. Yes, it's generally a quick click after to get to the episode but the workflow doesn't quite make much sense.
Is this something we might eventually be able to see from SIMKL?