Skip to main content
GET
/
api
/
episodes
/
getEpisode
Get Episode
curl --request GET \
  --url https://api.example.com/api/episodes/getEpisode
{
  "data": {
    "id": "<string>",
    "anime_mal_id": 123,
    "episode_id": 123,
    "video_url": "<string>",
    "image_url": "<string>",
    "title": "<string>",
    "description": "<string>",
    "date": "<string>"
  },
  "Retry-After": {}
}

​
Overview

This endpoint returns detailed information for a specific episode identified by the anime’s MyAnimeList ID and episode number.

​
Authentication

This endpoint does not require authentication.

​
Rate Limiting

This endpoint is protected by rate limiting middleware:
  • Default limit: 100 requests per 60 seconds
  • Returns 429 Too Many Requests when limit is exceeded
  • Includes Retry-After header in rate limit responses

​
Query Parameters

​
mal_id
string
required
The MyAnimeList (MAL) ID of the anime. This parameter is required to identify which anime the episode belongs to.Example: 52991
​
ep
string
required
The episode number to retrieve. This parameter is required.Example: 1

​
Response

​
data
object
Episode object containing detailed information
​
id
string
Unique identifier for the episode
​
anime_mal_id
number
MyAnimeList ID of the parent anime
​
episode_id
number
Episode number within the series
​
video_url
string
URL to the video stream for this episode. Can be used with video players like Vidstack.
​
image_url
string
Thumbnail or preview image URL for the episode
​
title
string
Episode title (if available)
​
description
string
Episode description or synopsis (if available)
​
date
string
Air date or release date of the episode in ISO format (if available)

​
Example Request

curl -X GET "https://anidev.vercel.app/api/episodes/getEpisode?mal_id=52991&ep=1"

​
Example Response

{
  "data": {
    "id": "ep-52991-1",
    "anime_mal_id": 52991,
    "episode_id": 1,
    "video_url": "https://example.com/video/one-piece-ep1.m3u8",
    "image_url": "https://example.com/thumbnails/one-piece-ep1.jpg",
    "title": "I'm Luffy! The Man Who Will Become Pirate King!",
    "description": "Monkey D. Luffy sets sail to find the legendary One Piece treasure and become the Pirate King.",
    "date": "1999-10-20T00:00:00.000Z"
  }
}

​
Error Responses

​
Missing MAL ID Parameter

Status Code: 400 Bad Request 
{
  "error": "Missing mal_id parameter",
  "type": "validation"
}

​
Missing Episode Number

Status Code: 400 Bad Request 
{
  "error": "Missing episode number",
  "type": "validation"
}

​
Episode Not Found

Status Code: 404 Not Found 
{
  "error": "Episode not found",
  "type": "notFound"
}

​
Rate Limit Exceeded

Status Code: 429 Too Many Requests 
{
  "error": "Too many requests, please try again later",
  "type": "tooManyRequests"
}
​
Retry-After
header
Number of seconds to wait before making another request

​
Server Error

Status Code: 500 Internal Server Error 
{
  "error": "Internal server error"
}

​
Implementation Details

This endpoint uses Redis caching to improve performance. Episode data is cached with a configurable TTL to reduce database queries and improve response times.
The video_url field may return streaming URLs that require proxy handling. Use the /api/videoProxy endpoint if you encounter CORS issues when streaming videos.

​
Use Cases

​
Video Player Integration

This endpoint is designed to work seamlessly with video players like Vidstack: 
import { MediaPlayer, MediaProvider } from '@vidstack/react';

const VideoPlayer = ({ malId, episodeNumber }) => {
  const [episode, setEpisode] = React.useState(null);

  React.useEffect(() => {
    fetch(`/api/episodes/getEpisode?mal_id=${malId}&ep=${episodeNumber}`)
      .then(res => res.json())
      .then(({ data }) => setEpisode(data));
  }, [malId, episodeNumber]);

  if (!episode) return <div>Loading...</div>;

  return (
    <MediaPlayer src={episode.video_url} poster={episode.image_url}>
      <MediaProvider />
    </MediaPlayer>
  );
};

​
Progress Tracking

Combine with user preferences to track watching progress: 
const trackEpisodeProgress = async (malId, episodeNumber) => {
  const episode = await fetchEpisode(malId, episodeNumber);
  
  // Save to user's watch history
  await fetch('/api/user/watchHistory', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      anime_mal_id: episode.anime_mal_id,
      episode_id: episode.episode_id,
      timestamp: Date.now()
    })
  });
};
  • List Episodes - Get all episodes for an anime with pagination
  • Video Proxy - Proxy endpoint for streaming video content
  • Get Anime - Get detailed information about the parent anime

Build docs developers (and LLMs) love

Get started for freeTalk to us