Find items by external ID
Never call search before scrobbling or marking something watched.
This is the most common wasted request we see. Apps look the title up here first to get a Simkl ID, then send that ID to the write endpoint. The lookup is unnecessary. Every write endpoint resolves the item itself, from whatever you already have:
Pass any combination of IDs, plus title and year as fallbacks, in the same request that records the watch. Simkl matches it server-side. A Simkl ID is never required.
That applies to /scrobble/*, POST /sync/history, POST /sync/add-to-list and POST /sync/ratings alike.
Searching first doubles your request count for no benefit, burns rate limit you’ll want later, and picks the wrong title whenever the search ranking disagrees with the IDs you already hold. One call, not two.
Use search only when you have no usable IDs at all: a title the user typed, a file name, or a random pick.
⚠️ Prefer
GET /redirect+ a cached detail endpoint over/search/idfor almost every external-ID lookupThe recommended two-step flow is materially cheaper, faster, and edge-cached:
Step 1 — Resolve the external ID to a Simkl ID. Call
GET /redirect?to=simkl&<external_id>=…and read (don’t follow) theLocationheader. Parse the Simkl ID out of the URL path. No JSON body to download, no JSON to parse — just HTTP headers.Step 2 — Fetch the full record from the cached detail endpoint. Use the parsed Simkl ID with the matching:
- Movies →
GET /movies/{simkl_id}- TV shows →
GET /tv/{simkl_id}- Anime →
GET /anime/{simkl_id}- Episode lists →
GET /tv/episodes/{simkl_id}orGET /anime/episodes/{simkl_id}These detail endpoints are Cloudflare-cached by Simkl ID with automatic server-side cache invalidation on metadata updates. Popular titles come straight from the edge cache and cost almost nothing.
Why this beats
/search/id:
/redirectreturns just HTTP headers (no JSON body)./search/idreturns JSON every call.- The detail endpoints are Cloudflare-cached.
/search/idis a search query that hits origin every time.- Two requests both cheap > one request that always hits origin.
- Concurrent / parallel lookups against the cached detail endpoints are explicitly allowed (see Rate limits → Parallel requests).
/search/idshould be called sequentially.When
/search/idis still the right call (rare):
- You need the legacy response shape for a code path you can’t change.
- You need a type-agnostic lookup that returns the
typefield upfront without parsing theLocationURL.
Look up Simkl records by any external ID — IMDB, TMDB, TVDB, MAL, AniDB, AniList, Kitsu, anisearch, anime-planet, livechart, letterboxd, Netflix, Trakt slug. Pass the ID as a query parameter (e.g. ?imdb=tt4574334).
Response shape (per item)
status is one of released, upcoming, ended, aired, tba. total_episodes is omitted for movies.
Redirect & deep-linking — recommended alternative
Full walkthrough of the two-step /redirect → cached detail endpoint flow, with the stop-at-301 reference table for popular HTTP clients and worked recipes in bash, JavaScript, and Python.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
Headers
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
AniFox / anfo.org ID. Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
Anime News Network (ANN) ID. Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
TV.com ID (legacy). Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
Zap2it (TVScheduleDirect) ID. Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
Trakt URL slug. Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
Letterboxd film slug (movies). Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
Letterboxd alias — same as letterboxd. Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
MyDramaList slug or ID (Korean / Asian dramas). Returns the matching Simkl title(s). See Standard media objects → Supported ID keys.
Response
Array of matching catalog records — [] when no record matches the supplied IDs. There is no 404 for unknown IDs; an empty array is the not-found shape (Type 3 null — see Null and missing values).
Release / airing status. released / upcoming apply to movies; ended / aired / tba apply to TV and anime. Note this enum is broader than the closed {tba, ended, airing} set the detail endpoints (/tv/{id}, /anime/{id}) use — /search/id is built on a different code path.
released, upcoming, ended, aired, tba Identifiers returned inside each /search/id result item. The server returns ONLY simkl and slug here — even when you queried by imdb, tmdb, tvdb, mal, etc., the response does NOT echo the input ID back in this block. To get the full canonical external-ID set for the matched record, follow up with the per-type detail endpoint (GET /movies/{simkl}, GET /tv/{simkl}, GET /anime/{simkl}) — those carry the full ID set.
Type 4 null — data not on file in that field's slot. See Null and missing values. Poster image path. See Images for how to build the URL.
Type 4 null — data not on file in that field's slot. See Null and missing values.