Skip to main content

​
Endpoint

GET /api/animes/random

​
Description

Retrieve a randomly selected anime from the database. This endpoint is perfect for anime discovery features, “surprise me” functionality, or recommendation systems. The random selection can optionally respect parental control settings and user preferences.

​
Authentication

This endpoint is publicly accessible and does not require authentication. However, providing a user_id can personalize the random selection.

​
Rate Limiting

  • Limit: 100 requests per 60 seconds per IP
  • Headers: Rate limit information included in response headers

​
Query Parameters

​
parental_control
boolean
default:"true"
Apply parental control filtering to exclude mature content from random selection.Set to false to include all anime regardless of rating.Example: parental_control=false
​
user_id
string
Optional user identifier for personalized random selection. When provided, the algorithm may consider user preferences, watch history, or favorites to improve recommendations.Example: user_id=user_123abc

​
Response

​
data
object
Random anime object
The response intentionally returns minimal data (only mal_id and title) to keep the endpoint fast. Use the returned mal_id with the Get Anime Details endpoint to fetch complete information.

​
Examples

​
Basic Random Anime Request

curl -X GET "https://your-domain.com/api/animes/random"

​
Random Anime Without Parental Control

curl -X GET "https://your-domain.com/api/animes/random?parental_control=false"

​
Random Anime with User Context

curl -X GET "https://your-domain.com/api/animes/random?user_id=user_abc123"

​
Get Random Anime Then Fetch Full Details

// Step 1: Get random anime
const randomResponse = await fetch('https://your-domain.com/api/animes/random');
const randomData = await randomResponse.json();
const animeId = randomData.data.mal_id;

// Step 2: Fetch full details
const detailsResponse = await fetch(`https://your-domain.com/api/animes/getAnime?id=${animeId}`);
const animeDetails = await detailsResponse.json();

console.log('Full anime details:', animeDetails.data);

​
Response Example

{
  "data": {
    "mal_id": 5114,
    "title": "Fullmetal Alchemist: Brotherhood"
  }
}

​
Error Responses

​
No Anime Found (404)

{
  "error": {
    "message": "No random anime found",
    "type": "notFound",
    "statusCode": 404
  }
}
This error is rare but can occur if:
  • The database is empty
  • All animes are filtered out by parental control
  • There’s an issue with the random selection algorithm

​
Rate Limit Exceeded (429)

{
  "error": {
    "message": "Too many requests. Please try again later.",
    "type": "rate_limit",
    "statusCode": 429
  }
}

​
Internal Server Error (500)

{
  "error": {
    "message": "Failed to fetch random anime",
    "type": "database",
    "statusCode": 500
  }
}

​
Features

​
Parental Control

When parental_control=true (default), the random selection:
  • Excludes anime with mature ratings (Rx - Hentai)
  • Only selects from age-appropriate content
  • Ensures family-friendly recommendations

​
User-Aware Selection

When a user_id is provided, the random selection algorithm may:
  • Avoid animes the user has already watched
  • Prefer genres the user enjoys
  • Consider the user’s rating history
  • Weight recommendations based on favorites
The exact personalization logic depends on the backend implementation and available user data.

​
Performance Characteristics

  • Fast Response: Returns minimal data for quick loading
  • No Caching: Each request generates a new random selection
  • Database Optimized: Uses efficient random sampling queries

​
Use Cases

​
Discovery Features

// "Surprise Me" button implementation
const getSurpriseAnime = async () => {
  const randomResponse = await fetch('/api/animes/random');
  const { data } = await randomResponse.json();
  
  // Redirect to anime details page
  window.location.href = `/anime/${data.mal_id}`;
};

​
Recommendation Widget

// Daily anime recommendation
const getDailyRecommendation = async (userId) => {
  const response = await fetch(`/api/animes/random?user_id=${userId}`);
  const { data } = await response.json();
  
  // Fetch full details for display
  const detailsResponse = await fetch(`/api/animes/getAnime?id=${data.mal_id}`);
  const anime = await detailsResponse.json();
  
  return anime.data;
};

​
Random Anime Generator

// Generate multiple random anime suggestions
const getRandomSuggestions = async (count = 5) => {
  const suggestions = [];
  
  for (let i = 0; i < count; i++) {
    const response = await fetch('/api/animes/random');
    const { data } = await response.json();
    suggestions.push(data);
  }
  
  return suggestions;
};

​
Explore Feed

// Infinite scroll exploration feed
const loadMoreRandomAnimes = async (limit = 10) => {
  const promises = Array.from({ length: limit }, () =>
    fetch('/api/animes/random').then(r => r.json())
  );
  
  const results = await Promise.all(promises);
  const animeIds = results.map(r => r.data.mal_id);
  
  // Fetch full details for all random animes
  const detailsPromises = animeIds.map(id =>
    fetch(`/api/animes/getAnime?id=${id}`).then(r => r.json())
  );
  
  return Promise.all(detailsPromises);
};
Calling this endpoint multiple times in quick succession may return duplicate animes. Implement client-side deduplication if uniqueness is required.
Best Practice: For better user experience, fetch full anime details immediately after getting the random selection, rather than showing just the title.
  • Get Anime Details - Fetch complete information using the returned mal_id
  • Get Animes - Browse animes with filters instead of random selection

Build docs developers (and LLMs) love

Get started for freeTalk to us