Recently changed catalog items

Returns Simkl catalog IDs whose metadata changed in the last N days, grouped by type. Use it to keep the items already on a user’s watchlist fresh — when a show airs a new episode, an upcoming title starts airing, or a movie’s metadata is updated, the corresponding ID appears here.

How tracking apps use it

You already know which items the user is tracking from the Sync guide loop (GET /sync/activities + GET /sync/all-items with date_from=). That tells you when the user touched their lists. /changes is the complementary call — it tells you when Simkl’s catalog metadata for any item moved, independent of whether the user touched their list. New episodes that just aired, a show whose status flipped from upcoming to airing, a movie whose runtime / poster / overview was updated.

When to actually call it

Treat it like Sync: trigger on a user-visible event, never on a background timer. The intended cadence is at most once per day per user, gated on a stored timestamp:

The loop (when the trigger fires)

1. Call /changes?date_from=<last_changes_poll>. Narrow with type= to only the catalogs the user has items in (skip anime if the user has no anime, etc.).
2. Intersect in your client: {IDs the response returned} ∩ {IDs the user has on any watchlist}. You already have the user’s watchlist locally from the Sync loop — this is a Set lookup, ~microseconds.
3. Apply the skip rules below to the intersection. Most items get dropped here — only the ones where new metadata is plausible survive.
4. For each surviving ID, refetch the matching cached endpoint:

The detail endpoints are edge-cached by Simkl ID, so popular titles come straight from Cloudflare without hitting origin. When an item’s metadata or episodes change, Simkl automatically purges its Cloudflare cache entry — so a refetch right after /changes flagged the ID is guaranteed to return the fresh data, never a stale edge copy. After the refetch, save now() as last_changes_poll.

Skip rules — when not to refetch

First, restrict the intersect to active lists. Items on the user’s completed and dropped lists are titles they’re done with — there’s no UX win in refreshing metadata for a show they’re never opening again. Intersect /changes only against items on watching, plantowatch, and hold (plus their anime equivalents); drop the rest before you even consider a refetch.

After that filter, the remaining items still benefit from status-based throttling. Cache the last-known status (TV/anime) or release state (movies) for each item in the user’s watchlist, and track the last time you refetched each item. Use the rules below — most items will sit in a state where new metadata is implausible.

The intersect + skip combination typically reduces a /changes response of tens of thousands of IDs down to a handful of detail-endpoint refetches per day per user — even for power users with very large libraries.

Query parameters

Response shape

An object with up to three keys (movies, shows, anime), each an array of integer Simkl IDs. Keys are omitted when their bucket is empty. If nothing changed in the window, the response is {} (an empty object, NOT []).

{
  "movies": [
    56145,
    1029384
  ],
  "shows": [
    17465,
    92834
  ],
  "anime": [
    39687
  ]
}

IDs are returned in no particular order. Items modified in the last 5 minutes are excluded so partially-written records don’t leak into the delta. Each response contains at most 50,000 IDs — if the catalog produces more (rare; only on very wide windows across all three types), narrow the call with type= to fit under the cap.