Feature request — a "significant change" signal so clients don't waste API calls

[MaxHasADHD]

Subject: Feature request — a "significant change" signal so clients don't waste API calls discovering cosmetic updates

TL;DR: updated_at and /shows/updates fire on any change, including cosmetic ones (votes, rating, translations). Clients can't tell what changed without spending an API call to find out — usually that nothing relevant did. On larger libraries this burns through the 1000-req/5-min limit and stalls user syncs. Please add a server-side way to detect significant changes only (new/removed episodes, airdate changes incl. TBA→real, title changes, status) — ideally a ?changes= filter on /shows/updates, or a separate content_updated_at timestamp. Counts alone aren't enough (placeholder-date→real-date changes don't move the count).

Hi Trakt team,

I maintain a TV tracking app (Television Time) that syncs user libraries against Trakt. I've hit a structural problem with change detection that I think affects any client trying to stay in sync efficiently, and I'd like to propose a way forward.

The problem

To keep a user's library current I need to know which shows have meaningfully changed since their last sync. The signals available are updated_at (on show/season objects) and GET /shows/updates/id/{since}. Both fire on any change to the object — including ones with zero relevance to a tracking client: votes, rating, comment_count, translations, images, and similar. Trakt tells me "this show changed" but not what changed, so my only option is to spend an API call (often a full seasons+episodes fetch) to discover that the only thing that moved was the vote count.

This doesn't scale with library size. A recent real example from my own account:

• GET /shows/updates/id/{since} over a ~8-day window reported 28,146 shows updated.
• My library contained 270 intersecting shows; that I then had to verify
• Because most of those "updates" were cosmetic, the majority of the resulting season/episode calls returned data identical to what I already had.
• I hit the 1000 requests / 5 minutes rate limit mid-sync and got Retry-After: 300. For a user, sync stalls 5+ minutes; on larger libraries it can fail to complete in a session at all.

The rate limit is doing its job — but a large fraction of the calls it throttles are calls Trakt effectively required me to make to rule out irrelevant changes.

What counts as "significant" (and why counts alone aren't enough)

The hard part is that significance isn't just "episode count changed." A very common pattern: an upcoming episode is created with a placeholder/TBA airdate, then later its real airdate and title are filled in. Throughout that, aired_episodes and episode_count stay identical — but the change absolutely matters to my users, who are waiting to see when the episode airs.

So a useful definition of significant would include changes to:

• episode/season added or removed (counts)
• episode airdate (including TBA → real date)
• episode or season title
• show status (e.g. returning → ended/canceled)
• aired/unaired transitions

…and would exclude cosmetic fields: votes, rating, comment_count, translations, images, overview tweaks.

What would fix it

Both of these put classification on the server, which is the only side that can do it without forcing a fetch:

1. A ?changes= filter on the updates endpoint — e.g. GET /shows/updates/id/{since}?changes=episodes,airdates,titles,status, returning only shows where a change in one of those categories occurred. Most direct fix: it lets the client ask exactly the question it has.

2. A separate content_updated_at (or significant_updated_at) timestamp on objects that only bumps for the significant categories above, leaving the existing updated_at as the "anything changed" field. Clients diff against whichever one matters to them. A per-object content hash/ETag covering only the significant fields would serve the same purpose.

Either would dramatically cut the calls clients make against your API — a win for your infrastructure as much as for my users.

Alternatives I've considered and why they fall short

• Comparing aired_episodes/episode_count myself: I'm already doing this where the data's in hand (list/watched responses). But it can't catch the placeholder-date→real-date or title-correction cases above, where counts don't change, so it's a partial filter at best — not a substitute for a real significance signal.
• Returning counts in the /shows/updates response: would help the common votes-only case, but has the same blind spot — it can't represent an airdate or title change, so I'd still miss real updates.
• Backing off to less frequent syncs: degrades freshness and doesn't reduce wasted calls, just spreads them out.

Happy to share more detail or real request logs if useful. Thanks for maintaining the API — this is the one piece that would let clients be both fast and gentle on your servers.

[MaxHasADHD]

I also noticed that GET https://api.trakt.tv/shows/updates/id/{date} is using a limit of 100, even when passing in 250. Is that intentional? When my app syncs I make a call to GET /sync/last_activities, and only fetch changes for the users watchlist, history, etc when there has been a change since last sync. Its possible that there have been no changes, but I still need to keep the cached series data up to date. I thought the GET /shows/updates/id/{date} would help direct me towards series that would actually need changes, but its actually eating a third to a half of my API limit, and still returning a wide net of shows to update.

[rectifyer]

Internally, we already use a separate timestamp that is updated when the metadata is refreshed and not on any change such as play count. We don't store an audit trail for each individual field and when it is updated, so your first suggestion is unfortunately not possible. The 2nd suggestion should already be in place (the previously mentioned refreshed timestamp we use). Do have a more specific comparison for a show or movie with what you consider minor changes triggering the item to be flagged as updated?

[MaxHasADHD]

@rectifyer Thanks, that's helpful, and good to know you don't keep a per-field audit trail.

To answer your question first: the changes I care about for sync are structural — episodes added/removed, an airdate appearing or shifting (including TBA → real), a title filling in, and status changes like returning → ended. The fields I'm personally less focused on for sync are votes, rating, and comment_count — not that they aren't important (they clearly are on a social platform, and I use that data elsewhere in the app), but with the 1000-req/5-min limit I have to prioritize changes to the show itself and the user's account. Which raises one question on your reply: you said the refreshed timestamp isn't bumped by play count — does it also stay put for votes, rating, or comment_count? That's the crux of whether /shows/updates reads as noisy on my end.

But that field-level noise is really a symptom of a bigger structural gap, so let me walk through my sync flow — because up to a point, the API lets me be very efficient:

1. GET /sync/last_activities to check whether the user's watchlist or history changed.
2. If they did, I fetch the relevant lists — e.g. GET /sync/watchlist/shows — and update from there. If nothing changed, I skip those calls entirely. Efficient so far, exactly as intended.
3. But a show already on the user's list can change when the user does nothing — a new season or episodes, a status change, an airdate or title firming up. last_activities can't tell me that, because the user's account didn't change.

To catch those, my only options today are:

• GET /shows/{id} for every show a user follows — wasteful, since most didn't change, or
• GET /shows/updates/id/{since} — but it's global, so finding the ~270 of a user's shows that changed means paging the entire feed (~28,000 ids, ~281 requests over an 8-day window), more than a quarter of the budget before I've fetched a single show.

So there's the gap: last_activities handles "the user changed something" really well, but nothing handles "a show the user follows changed" without either hitting every show individually or downloading the whole catalog.

The fix that sidesteps the audit-trail problem entirely: an id-filtered version of /shows/updates — pass the ids I track (plus the since date), get back only the ones from that set that changed. It doesn't need to know what changed, just to scope the existing feed to a client's library. That turns those ~281 discovery calls into one or two — and honestly, if discovery were that cheap, the cosmetic-noise problem mostly takes care of itself, since the expensive part isn't verifying a show, it's finding which ones to verify.

Thanks again for digging into this.

[betablon]

Second client hitting the same wall — and a direct answer to @rectifyer's outstanding question:

Do have a more specific comparison for a show or movie with what you consider minor changes triggering the item to be flagged as updated?

Measured on my own library today (2026-07-20), ~175 tracked shows:

• 24h window on /shows/updates/id/{since} → 11,518 shows, 116 pages at the enforced limit of 100.
• 123 of my 175 tracked shows flagged - 70% of the library, in one day. Signal-to-noise ≈ 1.07%.
• I then fetched /shows/{id}?extended=full for 40 of those 123 and diffed against my cache, restricted to the fields I actually sync on (runtime, status, network, aired_episodes):

sampled 40 flagged shows
  nothing changed in the fields I consume : 40
  something changed                       :  0

40/40 cosmetic. So the report reproduces independently. (Caveat: one library, one 24h window, 40-show sample - happy to run a wider one if useful.)

The arithmetic for a 175-show library:

approach	requests/day
/shows/updates + hydrate what it flags	116 + 123 = 239
blindly re-fetch every tracked show	175
today: one /sync/watched/shows?extended=full, gated per-show on updated_at	1

The change signal costs more than ignoring it. That isn't a tuning problem - the feed is sized by the catalogue rather than by my library, so it can't pay at any small or mid-size library.

Two things that may be new to the thread:

1. Timestamps are honored now. api-help#17 (2019) reported them accepted but ignored, giving whole-day granularity. Today ?since=2026-07-20T18:00:00Z really does narrow the window. That's a genuine improvement - thank you.
2. But the volume is batched, not smooth, which is why (1) doesn't rescue it. Same day, UTC:

 1h ago →     3       4h ago →  3,200      12h ago → 10,007
 3h ago →    22       8h ago →  3,216      24h ago → 11,518

Bulk metadata refreshes land a few times a day. Between them almost nothing moves; across one, ~70% of any library is flagged. So no window size avoids the cost - it only changes when you pay it.

Also still true: limit=250 and limit=1000 both come back x-pagination-limit: 100, so #354 is load-bearing here too.

Why I think this is more urgent than when it was filed.

In #837 the guidance was that /sync/watched/shows is no longer the source for show metadata and clients should hydrate from /shows/{id}?extended=full. The caching rationale makes sense to me. But that sync response is currently the only cheap change signal in the API: one request returns every show I track with a per-show updated_at, so I can gate hydration precisely and usually do nothing at all.

/shows/updates is the documented replacement for that signal, and the numbers above are why it can't serve as one. So the two changes interact: #837 removes the workaround that makes #813 survivable. If sync-embedded updated_at goes away before something like content_updated_at exists, clients lose cheap change detection with no fallback except periodically re-fetching whole libraries - which I'd guess is the opposite of what the caching change is meant to achieve.

Given your note that you already maintain an internal timestamp bumped on metadata refresh rather than on any change, exposing that - as a field on the show object, or as a ?changes= filter on /shows/updates - would close this completely. Happy to test against whatever shape you'd like to try.