> ## Documentation Index > Fetch the complete documentation index at: https://api.simkl.org/llms.txt > Use this file to discover all available pages before exploring further. # List episodes for an anime > Returns the full episode list for a Simkl anime ID, including specials. For anime, season is omitted in regular episodes (anime is treated as a single canonical season per AniDB); specials use `type: "special"` and lack a `season`/`episode` pair. #### Item shape ```json { "title": "To You, in 2000 Years", "description": "...", "episode": 1, "type": "episode", "aired": true, "img": "https://wsrv.nl/?url=https://simkl.in/episodes/...&q=90", "date": "2013-04-07T00:00:00+09:00", "ids": { "simkl_id": 1010234 }, "tvdb": { "season": 1, "episode": 1 } } ``` `tvdb.season` / `tvdb.episode` reflect the original TVDB numbering when AniDB mapping diverges. Responses are **Cloudflare-cached by Simkl ID**, so repeat lookups of popular anime are near-free. Parallel requests against this endpoint are explicitly allowed (see [Rate limits → Parallel requests](/resources/rate-limits#parallel-requests--when-allowed)). **Cache invalidation is automatic.** When Simkl updates the underlying episode list (new episode airs, airdate change, title edit, image swap, etc.), the corresponding Cloudflare cache entry is purged server-side. The next call returns the fresh data — there's no TTL to wait out. Your own app-level cache, if any, still has to be invalidated by your client. Use the parent anime's Simkl ID. If you only have an external ID (MAL, AniDB, AniList, Kitsu, …), resolve it via [`GET /redirect`](/api-reference/redirect) first. Errors: `400 empty_id` if `id` is missing. ## OpenAPI ````yaml /openapi.json get /anime/episodes/{id} openapi: 3.1.0 info: title: Simkl API version: 1.0.0 description: >- The **Simkl API** lets you build apps that track Movies, TV Shows, and Anime — scrobble playback, sync watch history, and pull rich metadata. All requests use HTTPS and return JSON. The base URL is `https://api.simkl.com`. **Every request needs three URL parameters and a `User-Agent` header:** ``` /endpoint?client_id=YOUR_CLIENT_ID&app-name=my-app&app-version=1.0 ``` See [Headers and required parameters](/conventions/headers) for the full reference. Endpoints that read or modify a user's data also need an `Authorization: Bearer ` header — see [OAuth 2.0](/api-reference/oauth) or the [PIN flow](/api-reference/pin). > ⚠️ **About the auto-rendered cURL examples on each endpoint page:** they omit `?client_id=…&app-name=…&app-version=…` from the URL for brevity. **You must add them yourself when copy-pasting**, or use the interactive **"Try it"** playground (it fills them in for you). This is a Mintlify rendering convention — every Mintlify-built API doc behaves the same way. **Get started** - [Quickstart](/quickstart) — first request in 60 seconds - [API rules](/api-rules) — what's allowed, what isn't - [Standard media objects](/conventions/standard-media-objects) — the shapes every endpoint speaks - [Errors](/conventions/errors) — every status code Simkl returns contact: name: Simkl Developer Support url: https://support.simkl.com termsOfService: https://simkl.com/about/policies/terms/ license: name: Simkl API Terms of Use url: https://simkl.com/about/policies/terms/ x-logo: url: https://i.simkl.com/img_tv/apiary_logo_api.png backgroundColor: '#0E5DAB' altText: Simkl servers: - url: https://api.simkl.com description: Production API - url: https://data.simkl.in description: CDN for static, public data files (Calendar + Trending). No auth required. security: - clientId: [] - simklApiKey: [] tags: - name: OAuth 2.0 description: >- OAuth 2.0 authorization-code flow for web and mobile apps. The user is redirected to Simkl, signs in, approves your app, and is redirected back with a `code` you exchange for an `access_token`. Long-lived tokens — no refresh-token flow needed. externalDocs: description: OAuth 2.0 walkthrough url: https://api.simkl.org/api-reference/oauth - name: PIN description: >- Device flow for TVs, consoles, smart watches, CLI tools — anywhere typing a URL is hard. Show a 5-character code; user enters it on simkl.com/pin; you poll for the access token. **No `client_secret` required.** externalDocs: description: PIN flow walkthrough url: https://api.simkl.org/api-reference/pin - name: Redirect description: >- Helper redirects for one-click "mark as watched", trailers, sharing, and more. - name: Search description: Find shows, movies, and anime by ID, text query, file name, or randomly. externalDocs: description: Search guide url: https://api.simkl.org/guides/search - name: Movies description: >- Browse the Simkl movies catalog: details, premieres, top-of-best, and genre filters. - name: TV description: >- Browse the Simkl TV catalog: details, episodes, what's airing, premieres, top-of-best, and genre filters. - name: Anime description: >- Browse the Simkl anime catalog: details, episodes, what's airing, premieres, top-of-best, and genre filters. - name: Ratings description: >- Read Simkl's average community rating, rank, drop rate, and external ratings (IMDB, MAL) for any item, or for every item in a user's lists. - name: Scrobble description: >- Report real-time playback to Simkl with `start`, `pause`, and `stop`. At ≥ 80 % progress Simkl marks the item as watched automatically; below 80 % the session is saved as a paused playback the user can resume from any device. See [Standard media objects](/conventions/standard-media-objects) for the supported ID keys. ### Supported ID keys Inside any `ids` object, pass as many of these as you have. Simkl resolves to the canonical record. | ID key | Type | Example | |---|---|---| | `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. | | `imdb` | string | `tt1520211` | | `tmdb` | integer | `76757` (for TV, specify `type`) | | `tvdb` | int / string | `153021` or `the-walking-dead` | | `mal` | integer | `4246` (MyAnimeList) | | `anidb` | integer | `10846`. Specifying just this is enough for anime lookups. | | `anilist` | integer | `21` | | `kitsu` | integer | `12` | | `anisearch` | integer | `2227` | | `animeplanet` | string | `one-piece` | | `livechart` | integer | `321` | | `letterboxd` | string | `the-truman-show` | | `netflix` | integer | `70210890` (movie ID) | | `traktslug` | string | `john-wick-chapter-4-2023` | > 📖 Full reference: [Standard media objects](/conventions/standard-media-objects) externalDocs: description: Scrobble guide url: https://api.simkl.org/guides/scrobble - name: Sync description: >- Use Simkl as a cloud backup for the user's watch history and lists (Watching, Plan to Watch, On Hold, Dropped, Completed). **Always check [`/sync/activities`](/api-reference/simkl/get-activities) first** and sync only the lists that have moved. All write endpoints accept arrays — batch aggressively. See [Standard media objects](/conventions/standard-media-objects) for the supported ID keys. ### Supported ID keys Inside any `ids` object, pass as many of these as you have. Simkl resolves to the canonical record. | ID key | Type | Example | |---|---|---| | `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. | | `imdb` | string | `tt1520211` | | `tmdb` | integer | `76757` (for TV, specify `type`) | | `tvdb` | int / string | `153021` or `the-walking-dead` | | `mal` | integer | `4246` (MyAnimeList) | | `anidb` | integer | `10846`. Specifying just this is enough for anime lookups. | | `anilist` | integer | `21` | | `kitsu` | integer | `12` | | `anisearch` | integer | `2227` | | `animeplanet` | string | `one-piece` | | `livechart` | integer | `321` | | `letterboxd` | string | `the-truman-show` | | `netflix` | integer | `70210890` (movie ID) | | `traktslug` | string | `john-wick-chapter-4-2023` | > 📖 Full reference: [Standard media objects](/conventions/standard-media-objects) externalDocs: description: Sync guide url: https://api.simkl.org/guides/sync - name: Users description: User profile, settings, and watch statistics. externalDocs: description: Simkl API documentation url: https://api.simkl.org paths: /anime/episodes/{id}: get: tags: - Anime summary: List episodes for an anime description: >- Returns the full episode list for a Simkl anime ID, including specials. For anime, season is omitted in regular episodes (anime is treated as a single canonical season per AniDB); specials use `type: "special"` and lack a `season`/`episode` pair. #### Item shape ```json { "title": "To You, in 2000 Years", "description": "...", "episode": 1, "type": "episode", "aired": true, "img": "https://wsrv.nl/?url=https://simkl.in/episodes/...&q=90", "date": "2013-04-07T00:00:00+09:00", "ids": { "simkl_id": 1010234 }, "tvdb": { "season": 1, "episode": 1 } } ``` `tvdb.season` / `tvdb.episode` reflect the original TVDB numbering when AniDB mapping diverges. Responses are **Cloudflare-cached by Simkl ID**, so repeat lookups of popular anime are near-free. Parallel requests against this endpoint are explicitly allowed (see [Rate limits → Parallel requests](/resources/rate-limits#parallel-requests--when-allowed)). **Cache invalidation is automatic.** When Simkl updates the underlying episode list (new episode airs, airdate change, title edit, image swap, etc.), the corresponding Cloudflare cache entry is purged server-side. The next call returns the fresh data — there's no TTL to wait out. Your own app-level cache, if any, still has to be invalidated by your client. Use the parent anime's Simkl ID. If you only have an external ID (MAL, AniDB, AniList, Kitsu, …), resolve it via [`GET /redirect`](/api-reference/redirect) first. Errors: `400 empty_id` if `id` is missing. operationId: get-anime-episodes-id parameters: - name: id in: path description: >- **Simkl ID of the anime** — the parent anime's Simkl ID (not an individual episode ID). The endpoint returns the full episode list for that anime. Use a Simkl ID directly when you have one — the response is Cloudflare-cached. **If you only have an external ID** (MAL, AniDB, AniList, Kitsu, etc.), resolve it to a Simkl ID first via [`GET /redirect`](/api-reference/redirect). required: true schema: type: integer - $ref: '#/components/parameters/ClientIdQuery' - $ref: '#/components/parameters/AppNameQuery' - $ref: '#/components/parameters/AppVersionQuery' - $ref: '#/components/parameters/UserAgentHeader' responses: '200': description: >- Array of anime episode entries. Regular episodes are numbered sequentially (AniDB style — no `season` field); specials and movies in the listing carry `type: "special"`. When a TVDB mapping exists, a `tvdb` object pins down the corresponding TVDB season/episode for cross-referencing. Empty array `[]` for an unknown anime ID (Type 3 null). headers: {} content: application/json: schema: type: array items: $ref: '#/components/schemas/AnimeEpisodeDetail' examples: demon_slayer_first_episode: summary: >- Modern anime, regular episodes with TVDB mapping (Demon Slayer) description: >- Live data from `GET /anime/episodes/831411`. Note `season` is **omitted** (Type 2 — doesn't apply to anime); `tvdb` carries the TVDB mapping for the same episode. value: - title: Cruelty description: >- It is the Taisho Period. Tanjiro Kamado is living a modest but blissful life in the mountains with his family. One day, when he returns from selling charcoal in town, he finds his family slaughtered in pools of blood after a demon attack. episode: 1 type: episode aired: true img: 83/8351897a97a89d0e7 date: '2019-04-06T23:30:00+09:00' ids: simkl_id: 4170591 tvdb: season: 1 episode: 1 - title: Trainer Sakonji Urokodaki description: >- Tanjiro encounters a man named Giyu Tomioka who recommends he learn from a man named Sakonji Urokodaki. episode: 2 type: episode aired: true img: 83/8362c0d76f3a3a7f date: '2019-04-13T23:30:00+09:00' ids: simkl_id: 4170592 tvdb: season: 1 episode: 2 attack_on_titan_with_special: summary: Anime listing including a special / picture drama description: >- Older series where `description` and `img` may be `null` (Type 4) and specials follow the numbered episodes. Picture-drama entries carry `type: "special"` with no `episode` number. value: - title: >- To You, 2000 Years in the Future: The Fall of Zhiganshina (1) description: null episode: 1 type: episode aired: true img: 26/26148581d640c58b8 date: '2013-04-06T15:00:00+09:00' ids: simkl_id: 958466 - title: Picture Drama 3 description: null type: special aired: true img: 68/689124d248604d0d date: '2013-09-17T15:00:00+09:00' ids: simkl_id: 979612 unknown_id_empty: summary: Unknown anime ID — empty array (Type 3 null) description: >- When the parent anime's Simkl ID doesn't match any record, the response is `200 []`. value: [] '400': description: >- Empty path segment — the path was hit as `/tv/episodes/` or `/anime/episodes/` (no `id`). Provide a Simkl ID for the parent show or anime in the path. See [Standard media objects -> Supported ID keys](/conventions/standard-media-objects#supported-id-keys). content: application/json: schema: $ref: 093bfedf-7abd-4ee1-aaf6-c6c88a2c3029 examples: empty_id: summary: Empty `id` path segment value: error: empty_id code: 400 '412': $ref: '#/components/responses/ClientIdFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' security: - simklApiKey: [] components: parameters: ClientIdQuery: name: client_id in: query required: true description: >- Your **`client_id`** from your [Simkl developer settings](https://simkl.com/settings/developer/). Required on every request. schema: type: string example: YOUR_CLIENT_ID AppNameQuery: name: app-name in: query required: true description: >- Short, lowercase identifier for your app (e.g. `plex-scrobbler`, `kodi-bridge`). Helps Simkl identify which apps are using the API. schema: type: string example: my-app AppVersionQuery: name: app-version in: query required: true description: >- Your app's current version (e.g. `1.0`, `2.4.1`). Helps Simkl debug issues you report. schema: type: string example: '1.0' UserAgentHeader: name: User-Agent in: header required: true description: >- Descriptive identifier for your app, ideally `name/version`. Examples: `PlexMediaServer/1.43.1.10540`, `kodi-simkl/0.9.2`, `MyApp/2.4.1 (https://myapp.com)`. schema: type: string example: my-app/1.0 schemas: AnimeEpisodeDetail: type: object description: >- Anime episode listing entry returned by `GET /anime/episodes/{id}`. Same shape as `EpisodeDetail` except: - `season` is **omitted entirely** (Type 2 null) for regular TV-style anime episodes — AniDB numbers anime sequentially, not by season. Specials and movies that show up in the listing may carry `season`. - Adds an optional `tvdb` object with the corresponding TVDB season/episode mapping when available. AniDB and TVDB number anime differently, so this is the bridge for anime apps that index against TVDB. required: - episode - ids - title - type properties: title: type: string description: type: - string - 'null' season: type: integer description: >- Only present for specials and movies; omitted for regular TV-numbered episodes. episode: type: integer description: AniDB-style sequential episode number. type: $ref: '#/components/schemas/EpisodeType' aired: type: boolean img: type: - string - 'null' description: >- Type 4 null — data not on file in that field's slot. See [Null and missing values](/conventions/null-values). date: type: - string - 'null' description: >- Type 4 null — data not on file in that field's slot. See [Null and missing values](/conventions/null-values). tvdb: type: object description: >- TVDB season/episode mapping for cross-referencing against TVDB-indexed catalogues. Omitted when no TVDB mapping is on file. properties: season: type: integer episode: type: integer ids: type: object required: - simkl_id properties: simkl_id: type: integer EpisodeType: type: string enum: - episode - special description: >- Episode classification. `episode` for regular numbered episodes, `special` for one-off content (specials, clip shows, behind-the-scenes, picture dramas, etc.). On TV episode lists specials follow the regular run; on anime listings specials and movies share this enum. ErrorResponse: type: object description: >- Standard error envelope for 4xx and 5xx responses. Branch on `error` (machine-readable identifier) — `message`, when present, is human-readable guidance and is **not stable across releases**. properties: error: type: string description: >- Machine-readable error identifier. Stable across responses — use this for programmatic branching in client code. Examples: `user_token_failed`, `client_id_failed`, `empty_field`, `wrong_parameter`, `id_err`, `rate_limit`. example: user_token_failed code: type: integer description: >- HTTP status code echoed in the body for convenience — same value as the response status line. Always an integer. example: 401 message: type: string description: >- Human-readable error guidance. Optional — present on most errors, but not guaranteed. May reference the specific field or value that triggered the error. NOT stable; do not parse. example: Your client_id is wrong. Try another one required: - error - code responses: ClientIdFailed: description: >- Your `client_id` is missing, wrong, disabled, or has hit a request limit. Verify in your [developer settings](https://simkl.com/settings/developer/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: client_id_failed code: 412 message: Your client_id is wrong. Try another one RateLimited: description: >- Too many requests in too short a window. Back off and retry with exponential backoff — see [Rate limits](/resources/rate-limits) for the playbook. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate_limit code: 429 ServerError: description: >- Something is broken on Simkl's side. Retry after a short delay. If it persists, report on the [Simkl Discord](https://discord.gg/MJsWNE4). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: internal code: 500 securitySchemes: clientId: type: apiKey in: query name: client_id description: >- 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](/conventions/headers). x-default: YOUR_CLIENT_ID simklApiKey: type: apiKey in: header name: simkl-api-key description: >- Optional alias for the `client_id` query parameter. Simkl accepts your `client_id` either as the `simkl-api-key` request header **or** as the `?client_id=…` query parameter — pick one. The query-parameter form is preferred because it makes the request fully self-describing in URL form. x-default: YOUR_CLIENT_ID ````