‼️ Upcoming API Changes: Watched Endpoints Pagination & Extended Defaults

[kevincador]

Hi developers,

We’re sharing an early heads-up about upcoming changes to the watched endpoints.

This follows the pagination work already announced for lists, watchlist, favorites, collection/library, and other paginated endpoints. We’ve seen the feedback around timing, app release cycles, testing, and sync behavior, so we want to be more explicit here.

The (very) short version: paginate /watched and use the right extended parameter for your needs.

Update May 27, 2026: Based on developer feedback, we’re extending the rollout window. These changes will now be enforced after June 30, 2026 instead of May 30. Pagination is already available and optional, so apps/integrations can use them now.

---

Pagination changes

Pagination will be added and enforced on the watched endpoints:

• /users/{id}/watched/{type}
• /sync/watched/{type}

This applies to all supported types:

• movies
• shows
• and the 🆕 episodes type

Once enabled, these endpoints will return paginated responses instead of returning everything in one request.

Please don’t assume a single request returns a user’s full watched history.

You should explicitly send page and limit and keep requesting pages until you have everything you need.

Example:

GET /sync/watched/movies?page=1&limit=250

Then continue with:

GET /sync/watched/movies?page=2&limit=250

and so on until you have loaded all pages. We recommend stopping when you get an empty array [] response. You can also look at the pagination headers to get the total number of pages, but make sure your stop logic is robust.

Pagination defaults without limits

⚠️ By default, if you don’t send pagination parameters, you’ll get the first page of up to 100 items.
Pagination is currently enabled and optional. You can use page and limit now to test your integration before enforcement.

Max page size

The current target maximum page size is 250 when you request a limit.

For most paginated requests, that will be the upper limit per page.

However, we may reduce the effective page size when using heavier response modes, especially extended=progress (more on this one below), because that requires significantly more computation and returns much more data.

On the other hand, we may still return all watched data when you request extended=min (again more on this one below).

So, your integration should always send pagination information (except for extended=min if your intention is to get everything) and should never assume the requested limit is always the applied limit.

---

Extended changes

We’re also changing the default behavior of the extended parameter for these watched endpoints.

Current expectation

Today’s behavior is the following:

• if no extended parameters are requested: regular show information is returned with heavy season progress information
• extended=full: full show information is returned with heavy season progress information
• extended=noseason: regular show information is returned with no season progress information
• extended=full,noseason: full show information is returned with no season progress information

The problem with this is that a lot of apps use the default (nothing) or full response mode without needing the heavy season progress data.

New default

Going forward, the watched endpoints will return full show information with no season progress information.

So this:

GET /sync/watched/shows

will behave like the current extended=full,noseason.

Deprecated extended parameters

Sending extended=full, extended=noseason, or extended=full,noseason will no longer have any effect. Those parameters will be ignored and you will get the default.

Season progress information

If your app needs season progress data, you can explicitly request:

extended=progress

Example:

GET /sync/watched/shows?page=1&limit=250&extended=progress

Keep in mind that this request will return a lot of information and will be slower. Actual page limits may be lower than the 250 upper limit.

Minimal watched information

There is also a currently undocumented extended=min option that apps can start using now if they only need minimal watched information.

This returns a compact response with the Trakt ID as the key and an array of watched dates as the value.

Example response:

{
  "1342606": ["2026-02-27T22:17:00.000Z"]
}

This can be useful for apps that only need to compare watched states or sync dates without loading the full movies, shows or episodes metadata.

New extended behavior

So the new behavior is:

• default: full item information, no season progress
• extended=progress: includes season progress information
• extended=min: returns minimal watched information
• anything else will fall back to the default

---

Why we’re making this change

Watched history can get very large, especially for long-time users or apps doing full syncs.

Returning everything in one response is expensive, slower, and harder to scale reliably. It also makes it harder for us to keep the API consistent across endpoints.

Pagination makes the behavior clearer and more predictable:

• smaller responses
• faster requests
• better reliability
• less risk of timeouts
• more consistent behavior across the API
• better support for apps syncing large user accounts

The extended changes are also meant to make the default response more useful while keeping heavier computed data explicit and the min option really minimal.

---

What you should do now

Please review any code using:

/users/{id}/watched/{type}

or:

/sync/watched/{type}

and make sure you:

• send page and limit
• follow pagination patterns
• don’t assume one request returns everything
• don’t assume requesting 250 or 1000 or anything else will return that many items
• use extended=progress only when you actually need season progress data
• use extended=min if you only need minimal watched information

---

Timing

The goal of posting this now is to give everyone enough time to adjust, especially apps that need a full app release cycle and user updates before API behavior changes.

Expect these changes to take effect on May 30. We may extend that date if needed, so let us know if you need more time and why.

Pagination is enabled and optional on these endpoints, so you can start testing page and limit now. Pagination will become required after June 30, 2026.

---

TLDR

• /users/{id}/watched/{type} and /sync/watched/{type} are getting pagination
• supported types are movies, shows, and episodes
• default page size will be 250 when requesting a limit, 100 without a limit except for extended=min
• always handle pagination, don’t assume one request will return everything or the requested number of items
• full information will be returned by default, so extended=full is no longer required
• season progress will require the new extended=progress
• noseason becomes the default and won’t have any effect anymore
• extended=min can be used for a compact response with Trakt IDs and watched dates only

Please review your integrations and let us know if anything looks off.

Thanks for building with Trakt ✨

[jonathanantoine]

Hello,

Thanks for the heads-up! I have some questions :)

1 Episode trakt id

Previous parameter value returned only season-number+episode-number and not the episode-id directly when fetching progress.
New "min" parameter value returns only the traktid.

It would ease the transition if traktid was returned in the meantime so.

2 Episodes type

Also, what will be returned when using the new "episodes" type ?

3 Shape of the reply

Can you confirm that the body of the answer will stay unchanged ?

4 Number of plays

My app currently uses the number of plays and display it to the user.
Can you confirm that if I switch to "min", I will lose this information ?

[kevincador]

1. Episode trakt id

Previous parameter value returned only season-number+episode-number and not the episode-id directly when fetching progress.

This will still be the case for GET /sync/watched/shows?page=1&limit=250&extended=progress, if you think about using extended=min then the response is compacted.

It would ease the transition if traktid was returned in the meantime so.

I don't understand, this is always the case. The Trakt API runs on Trakt ID, you'll get them back as before with GET /sync/watched/shows?page=1&limit=250&extended=progress and you'll get them with extended=min (episodes for episodes, movies for movies and shows for shows).

2. Episodes type

Also, what will be returned when using the new "episodes" type ?

GET https://api.trakt.tv/users/me/watched/episodes?extended=min
{"14007201":["2026-04-23T19:02:00.000Z"],...}

GET https://api.trakt.tv/users/me/watched/episodes
[{"plays":1,"last_watched_at":"2026-04-23T19:02:00.000Z","last_updated_at":"2026-04-23T19:02:00.000Z","episode":{"season":4,"number":8,"title":"DON'T LEAVE ME HANGING HERE","ids":{"trakt":14007201,"tvdb":11572740,"imdb":"tt39848785","tmdb":6951284,"tvrage":null}}},...]

You can already use these, they're live

3. Shape of the reply

Can you confirm that the body of the answer will stay unchanged ?

Using the correct extended params, yes. If you use min no.

4. Number of plays

Can you confirm that if I switch to "min", I will lose this information ?

No, you won't loose it. You get an array of all the date watched.

[jonathanantoine]

Thank you for all the answers.

Previously progress does not return episode with id but just it's number (at least in doc and this is what I trusted) :

[UweTrottmann]

• How is the extended parameter changed for movies? It sounds like, besides extended=min, there will be no other values, correct?
• There won't be extended values, besides min, for the new episodes type, right? (Edit: it appears, it currently supports full. But will that then also be the default in the future?)
• Maybe the new min variant should be a separate method (or even split by type) as it has a different response data format?

Here are also the use cases in SeriesGuide to maybe help make decisions on what values to include in the min response so it (and other apps) could switch to it for syncing:

• Find a show by its TMDB ID
  • Get its last_watched_at
• Find a season by its number
  • Find an episode by its number
    • Get its plays

Thanks for your help!

[kevincador]

How is the extended parameter changed for movies? It sounds like, besides extended=min, there will be no other values, correct?

The only change for movies is the fact that you'll get full for free and min as an option. noseason already had no impact on movies, so does progress.

There won't be extended values, besides min, for the new episodes type, right? (Edit: it appears, it currently supports full. But will that then also be the default in the future?)

full should be the default everywhere, yes (cc @vladjerca)

Maybe the new min variant should be a separate method (or even split by type) as it has a different response data format?

This is an idea we entertained, but thought it would be a bigger breaking change than this one. For a V3 API, yes!

Here are also the use cases in SeriesGuide

Since you rely on TMDb ids, you won't be able to rely too much on the extended=min.
But pagination and extended=progress will get you to the same place.
Also taking your input into account for some internal discussions, I'll update here if we have something that better fits your needs.

[synclerd]

• May 30th gives roughly about 30 days to rework how history (core feature) is fetched (in addition to all the recent changes you have made). This is not enough. I advise that you look at it from an app developers perspective. Imagine if TMDB rolled out API v5 and told you to adjust in 30 days.
• Many apps including mine depend on TMDB ids, the season/episode numbers and plays to consolidate lists/history from various sources. I like the idea of min but without the aforementioned, it's useless for my usecase. So in the end after you rollout these changes, for Trakt users in Syncler the experience will be much slower because history fetch will take multiple requests, punishing the old og users the most because they are likely to have the most history.

I'd also like to give my feedback as a developer who has maintained Trakt integration for the last 5 years. I have been following all the changes you have made recently. All of this should have been rolled out as a new version of API with a 6-12 months deprecation notice for the current version of the API. Due to recent changes paired with recent downtimes, inconsistent http cache behavior, longer loading times, connection timeouts, many users have already chosen to turn off Trakt sync completely or move to a different service for sync or just use the in built sync Syncler provides. Do what you will with that information.

[kevincador]

May 30th gives roughly about 30 days to rework how history (core feature) is fetched (in addition to all the recent changes you have made). This is not enough. I advise that you look at it from an app developers perspective. Imagine if TMDB rolled out API v5 and told you to adjust in 30 days.

The change is limited to pagination and the extended parameters. We also have more than one app to maintain and adapt, our team is on the same schedule. We take time into account, that's why you have the possibility to adjust the extended parameters you are using to get the same responses as today. Pagination takes time to implement, but we're not expecting days or weeks to implement pagination.
Also, we are not TMDb and we are not rolling out a new API version, so the comparison you made is not valid.

Many apps including mine depend on TMDB ids, the season/episode numbers and plays to consolidate lists/history from various sources. I like the idea of min but without the aforementioned, it's useless for my usecase. So in the end after you rollout these changes, for Trakt users in Syncler the experience will be much slower because history fetch will take multiple requests, punishing the old og users the most because they are likely to have the most history.

You are not required to use the extended=min. Yes, that feature is optimized for apps using Trakt ids as primary source for syncing with Trakt via the Trakt API.
It will not be slower in the end. Taking a simple theoretical example: let's say a user has 5000 movies watched → one request could take 5 seconds to be fetched (if it is not erroring because of a time out or anything else). Now, what we're asking is to fetch 5 times 1000 movies but each requests will take 1 second, and you are sure it's not going to time-out. It is not slower to paginate.

Do what you will with that information.

Thank you for this feedback, it will be taken into account.

[SicMundus86]

I'm afraid 30 days notice is not reasonable in any way regardless of what your opinion on this would be. You aren't seeing how us app developers are having to restructure so many complex elements all the time to get around the extreme limitations this API already has. I will have to restructure and rewrite a large % of my code that I spent months cleverly getting API calls down thanks to TMBDs generous API, which without this would make the trakt API completely useless. You need to reconsider this 30 day timeframe.

[hegedus90]

I'm also maintaining my app as a side-project, thus I have very limited bandwidth. I'm pretty sure I won't be able to accommodate for these changes in 30 days. Personally, I would appreciate at least a 3 month notice. (If the pace of these API deprecations will remain this rapid, I'll probably just get rid of the Trakt integration completely.)

[synclerd]

Agreed. The pagination changes are not even deployed as per the comment below.

[damienhaynes]

If my app currently requests a limit of 1000 items per page on some requests, will the API safely return the max limit of 250 items and also give me the correct number of total pages back basis the new limit of 250 and not 1000?

e.g. there are 2000 items:
I request 1000 as a limit, you will give me max 250 with a total page count of 8? And not 250 items and 2 pages.

[UweTrottmann]

return the max limit of 250 items and also give me the correct number of total pages

I believe this is how it should work. Also quoting from above:

• follow pagination patterns
• don’t assume one request returns everything
• don’t assume requesting 250 or 1000 or anything else will return that many items

If you need something for testing, you could maybe use one of the existing methods (like for the watchlist) that supports pagination?

[javikr]

Hi Trakt team,

I’m testing pagination on the GET /sync/watched/movies endpoint and it looks like the page and limit query parameters are currently being ignored.

Example request:

GET https://api.trakt.tv/sync/watched/movies?page=31&limit=250

The response seems to return the same full/unpaginated watched movies payload instead of page 31 with 250 items. I also don’t seem to get useful pagination headers for this endpoint.

I wanted to confirm the expected behavior:

1. Is pagination for GET /sync/watched/movies already enabled in production?
2. Should page and limit work the same way as watchlist endpoints?
3. If not enabled yet, is the expected rollout still May 30, 2026?
4. Once enabled, should clients rely on X-Pagination-Page and X-Pagination-Page-Count headers to stop loading pages?

For context, this endpoint can return a large number of watched movies for long-time users, so pagination would help avoid very large sync responses.

Thanks!

[kevincador]

Hey,

1. Pagination has been enabled and is currently optional for those endpoints. You can use them now.
2. page and limit work like the watchlist endpoints, yes.
3. We are discussing the rollout date, I'll update the announcement soon with an update.
4. You can rely on X-Pagination-Page and X-Pagination-Page-Count, yes.

Thanks for your feedback!

[javikr]

Great. Thank you

[synclerd]

Hey, I had a concern/question about the new dynamic pagination behavior for /users/{id}/watched/{type} and /sync/watched/{type}.

What are clients supposed to do if page sizes change over time for the same request?

For example, say my app is requesting limit=250 and initially Trakt is only returning 100 items per page. A user browses to page 4, backgrounds the app, then comes back a few hours later and now the API starts returning 250 items per page (or fewer items on some pages).

Or even while the user is actively browsing the list:

• pages 1–3 were fetched when the API was returning 100 items
• then page 4 gets fetched after Trakt switches to 250 items per page

Now the page boundaries shift mid-session, which can cause:

• duplicate items between pages
• skipped/missing items
• broken infinite scroll state
• broken scroll restoration/cached page state

This seems especially problematic for Android/iOS apps where restoring previous pagination state is common.

Should clients basically treat page-number pagination as unstable now and fully refetch/dedupe everything every time? Or is the returned ordering/page composition expected to remain stable for the same limit? By making the limit potentially dynamic by completely ignoring the value sent you are making other devs life difficult. I have personally never seen this practice anywhere.

[kevincador]

Hey,

The use case you describe is not something we expect to happen in practice. If you ask for 250 and start getting, say, 100 items per page, you’ll continue to get 100 items per page for the following pages. We may tweak those maximum page sizes before the actual rollout and we may tweak them a bit after the rollout but don't expect them to change all the time, it won't be that dynamic.

About the background/session length, you currently have the exact same issue with history or other paginated endpoints. If you ask for page 1 and 2, then your user adds something in their history on the same device/app or another, then comes back to the history and you do not account for that change, you will get pages with either holes or duplicates. Our recommendation here would be to check for the last_activities and refetch from page 1 if needed but it all depends on your use case. TLDR there's a high probability that you will need to refetch from page 1 anyway.

Just to be clear, we are not completely ignoring the value you send but we are caping that value and, yes, that value is not yet set in stone for the extended=progress (we are still testing to find the sweet spot) but once we set a value, it will be documented and we won't dynamically change it all the time or send random page sizes.

Hope this clarifies things.
Thanks for your feedback!

[damienhaynes]

Perhaps you can allow more on the sync/ratings/episodes and movies endpoint? 1000 would be good if okay on you end?

Personally, for episodes, I need 75 pages at 250 per page:

{
"Transfer-Encoding": "chunked",
"Connection": "keep-alive",
"CF-Ray": "9ff07f68be0a5c05-SYD",
"CF-Cache-Status": "DYNAMIC",
"Access-Control-Allow-Origin": "*",
"Speculation-Rules": ""/cdn-cgi/speculation"",
"Vary": "Accept-Encoding, Origin",
"access-control-expose-headers": "X-Pagination-Page,X-Pagination-Page-Count,X-Pagination-Limit,X-Pagination-Item-Count,X-Trending-User-Count,X-Start-Date,X-End-Date,X-Sort-By,X-Sort-How,X-Private-User,X-Ratelimit,Retry-After,X-Upgrade-URL,X-Applied-Sort-By,X-Applied-Sort-How,Cache-Control,Pragma,Expires",
"referrer-policy": "strict-origin-when-cross-origin",
"x-content-type-options": "nosniff",
"x-download-options": "noopen",
"x-frame-options": "SAMEORIGIN",
"x-pagination-item-count": "18512",
"x-pagination-limit": "250",
"x-pagination-page": "75",
"x-pagination-page-count": "75",
"x-permitted-cross-domain-policies": "none",
"x-request-id": "e7600cb1-27ee-4d40-9d31-e6f6199c894a",
"x-runtime": "0.142210",
"x-xss-protection": "0",
"Cache-Control": "max-age=0, private, must-revalidate",
"Content-Type": "application/json; charset=utf-8",
"Date": "Thu, 21 May 2026 03:29:36 GMT",
"ETag": "W/"1294693c30004a699eac62a305019b3a"",
"Last-Modified": "Wed, 20 May 2026 12:50:18 GMT",
"Server": "cloudflare"
}

[martinr92]

Looks like there is a bug for the new /sync/watched/shows?page=1&limit=250&extended=progress endpoint:

The reset_at for a show is always null.

[AJDev77]

I'm seeing /sync/watched/shows?extended=progress&page=1&limit=250 ignoring season 0 in shows, but /sync/watched/shows reports those episodes.

[rectifyer]

@martinr92 Should have a fix out this week to make sure reset_at is always included.

@AJDev77 Should have a fix out this week to make sure specials are returned on the default endpoint.

[martinr92]

Thanks for the update. I re-tested it right now, but receiving only 500 server errors:
{\"error\":\"Internal Server Error\",\"breadcrumb\":\"handler.users.getUserWatchedShows\"}

[kevincador]

Thanks everyone for all the feedback.

We’re extending the transition window for these watched endpoint changes. Pagination is already enabled and optional, so you can start testing your apps/integrations with page and limit combined with the extended parameters you need.

The new behavior will not be enforced until after June 30, 2026.

I’ll update the original announcement to reflect the new target date.

[synclerd]

Will not be enforced?

The new behavior will not be enforced after June 30, 2026.

Do you have any plans to increase the API rate limit. With the new pagination requirements the number of request will increase without a doubt. And it will depend on the page size (which according to you is dynamic).

[kevincador]

Will not be enforced?

Fixed, sorry about that.

Do you have any plans to increase the API rate limit. With the new pagination requirements the number of request will increase without a doubt. And it will depend on the page size (which according to you is dynamic).

No plan, no. But let us know where you'd need increased rate limits.

Note: I've said that the new behavior will not be dynamic. There will be different limit depending on the data you request (via extended parameters) → If you need all the watched status in one page, you can use the new min, there's no pagination requirement on that one and it is fast. If you want more data and bigger pages, don't ask for progress. If you absolutely need progress, you can ask for it but will have to make more calls.

Reminder: if you’re using the API and auth as intended, you have 1000 authorized GET requests per user every 5 minutes. Do you really expect to reach that limit faster because of this change for a lot of your users? Most of the time, with 250 items per pages and if you want all the data, you'll get them in ~3 requests.

[synclerd]

On boot my app may need to rebuild various caches such as the user watchlist/personal list items/history/dropped shows etc, this is unavoidable especially when user has deleted history items and user is logging in for the very first time. In this case depending the user profile size (some users have watched thousands of episodes) it may need many more requests than it currently does. As of now I don't have any concrete numbers but since now we are expected to send multiple requests for the same data it's very obvious that we'll need higher number of requests.

Whether 1000 req./5 min will be enough, I don't know. It might fail for some users with large profiles. In my app I can add a warning for that before Trakt signing in.

The min does not work for my use-case as it does not have the TMDB ids for the shows. Trakt IDs are not universally recognized so it's useless for apps that support various other services. Min is also undocumented and I'm not sure deploying this to production yet will be a good idea.

[synclerd]

@kevincador
Pagination does not return an empty array when out of range in /sync/watched/shows?extended=progress&page=250&limit=250. Instead returns the duplicate data

[synclerd]

@kevincador Did you get a chance to look at this? Shipping this before June 30 is impossible at this point.

[dstmar]

I'm attempting to try out the pagination on /sync/watched/shows, and currently use extended=images,noseasons. Though the new pagination endpoint does seem to still work with noseasons, the images aren't returned. Will the images be returned when using the default extended after this June 30th cutoff or is the intended method to fetch images for shows individually using /shows/{id}? This would result in much higher volume of api requests. I've noticed the /sync/collection/shows has already removed the images, and have the same predicament if I want to get the poster for collected shows.

[ljransom]

You're much better off getting images from tmdb. You won't have to worry about the stingy API restrictions then. The tmdb API is very generous with their calls, it's the only way I can make use of trakt.

[betablon]

do mind tmdb's commercial api terms though..

[kevincador]

Update: thanks to everyone who tested this and shared feedback.

The watched endpoint changes are now live for /users/{id}/watched/{type} and /sync/watched/{type} across movies, shows, and episodes.

Final behavior:

• Requests without pagination now return page 1 with up to 100 items
• Explicit limit values are capped
• The general max page size is 250
• Pagination headers reflect the applied limit/page values, so clients should use those and not assume the requested limit was applied
• extended=min is the compact option for watched-state syncing and returns all data by default
• Season progress is no longer included by default; request extended=progress when you need it
• extended=progress is capped at 100 items per page because it includes heavier season/episode progress data
• noseasons is now effectively the default behavior and is a no-op parameter

Please continue to page through results until you have everything you need, and do not assume one request returns a complete watched history unless you are intentionally using extended=min.

Thanks again for the feedback 🙌

[betablon]

@kevincador
extended=progress on /sync/watched/{type} returns a minimal show object — is this intended?

Following the pagination + extended changes in this thread, extended=progress on /sync/watched/shows returns a much-reduced show object compared to the default response.
Comparing the same shows within one sync:

• Default (/sync/watched/shows): show includes title, ids, year, status, overview, network, rating, genres, runtime, first_aired, country, aired_episodes.
• extended=progress: show includes only title, ids, year, aired_episodes. status, overview, network, rating, genres, runtime, first_aired, and country are all absent.

I understand the announcement saying full item information is returned by default and extended=progress adds season progress — which reads as "full item info + season progress." In practice progress returns a minimal show object plus the season breakdown, i.e. it replaces the full metadata rather than extending it.

The impact: clients that need both season progress and show metadata now have to make two calls (default + progress) and merge by ID, or fall back to per-show lookups. If this is a bug — like the season-0 omission and null reset_at reported above — a fix would let progress serve as a single source. If it's intended, updating the docs to state that progress returns a minimal (not full) show object would save others the surprise.

[ghost]

Hi @kevincador,

Is there a way to add a movie to the watchlist via the API with a custom listed_at date?

I would like to set a specific backdated timestamp for when the item was added to the watchlist, rather than the system defaulting to the current UTC time. If this isn't currently supported by the API, are there any plans to add a timestamp parameter for watchlist syncs in the future?

Thanks in advance!

[kevincador]

That is not something that is supported by the API, no. But this is something we can consider adding in the future, yes! Thanks for your feedback!!

Note: don't hesitate to open a new Discussion for this kind of things.