---
title: "Similar Videos API"
description: "Find YouTube videos related to any target video by content topic and audience interest."
source: "https://dashboard.nexlev.io/docs/api/similar-videos"
---

# Similar Videos API

Find YouTube videos related to any target video by content topic and audience interest.

**Base URL**: `https://prod.dashboard.nexlev.io` — see [Authentication](/docs/api/authentication).

## Get Similar Videos

```http
POST /api/external/similar-videos/videos
```

**Description**: Discover YouTube videos that are similar to a given video using advanced similarity algorithms. Returns a ranked list of videos based on content, topics, and video characteristics.

**cURL Example**:

```bash
curl -X POST https://prod.dashboard.nexlev.io/api/external/similar-videos/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "xIL0ssyMh1k"}'
```

**Request Body**:

```json
{
  "videoId": "xIL0ssyMh1k"
}
```

**Body Parameters**: `videoId` (required) - YouTube video ID to find similar videos for

> **Warning**
>
> 🥞 **Quota Cost: 10 quota per request** — see [Rate Limits &
> Quota](/docs/api/rate-limits).

**Status Code**: `200 OK`

**Description**: Returns a list of videos similar to the target video, ranked by relevance. Each result includes video information, channel details, view count, and metadata about the video's performance and characteristics.

**Response Body**:

```json
[
  {
    "title": "Complete Guide to Content Creation in 2024",
    "similarity_score": 85,
    "format_score": 92,
    "type": "video",
    "videoId": "aB3cD4eF5gH",
    "channelTitle": "Digital Creators Hub",
    "channelId": "UCxYz123ABC456DEF789GHI",
    "channelThumbnail": [
      {
        "url": "https://yt3.ggpht.com/example-channel-thumb-1/s68-c-k-c0x00ffffff-no-rj",
        "width": 68,
        "height": 68
      }
    ],
    "description": "Learn everything you need to know about creating engaging content in 2024. From planning to execution, this guide covers it all...",
    "viewCount": "145230",
    "publishedTimeText": "3 weeks ago",
    "lengthText": "15:42",
    "thumbnail": [
      {
        "url": "https://i.ytimg.com/vi/aB3cD4eF5gH/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLExample1",
        "width": 360,
        "height": 202
      },
      {
        "url": "https://i.ytimg.com/vi/aB3cD4eF5gH/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLExample2",
        "width": 720,
        "height": 404
      }
    ],
    "richThumbnail": [
      {
        "url": "https://i.ytimg.com/an_webp/aB3cD4eF5gH/mqdefault_6s.webp?du=3000&sqp=CMzYu8kG&rs=AOn4CLExample",
        "width": 320,
        "height": 180
      }
    ]
  }
]
```

**Response Fields**:

- `title` - Video title
- `similarity_score` - Similarity score (0-100), higher indicates greater similarity
- `format_score` - Format similarity score (0-100)
- `type` - Content type (typically "video")
- `videoId` - Unique identifier for the video
- `channelTitle` - Name of the channel that uploaded the video
- `channelId` - Unique identifier for the video's channel
- `channelThumbnail` - Array of channel profile image objects
  - `url` - URL to the channel's profile image
  - `width` - Width of the channel thumbnail image
  - `height` - Height of the channel thumbnail image
- `description` - Video description/snippet
- `viewCount` - Raw view count (numeric string)
- `publishedTimeText` - Human-readable text of publish time (e.g., "3 weeks ago")
- `lengthText` - Video duration in MM:SS or HH:MM:SS format
- `thumbnail` - Array of video thumbnail objects with different sizes
  - `url` - URL to the video thumbnail
  - `width` - Width of the thumbnail image
  - `height` - Height of the thumbnail image
- `richThumbnail` - Array of animated/rich thumbnail objects (may be empty)
  - `url` - URL to the animated thumbnail
  - `width` - Width of the rich thumbnail
  - `height` - Height of the rich thumbnail

## Error Responses

### Bad Request

**Status Code**: `400 Bad Request`

**Description**: The request was invalid or malformed.

```json
{
  "error": {
    "code": 400,
    "message": "Invalid video ID format",
    "details": "Video ID must be a valid YouTube video identifier"
  }
}
```

### Unauthorized

**Status Code**: `401 Unauthorized`

**Description**: Authentication credentials are missing or invalid.

```json
{
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "details": "Invalid API key or credentials not provided. Create your API key at https://dashboard.nexlev.io/nexlev-api/create-api-key"
  }
}
```

### Not Found

**Status Code**: `404 Not Found`

**Description**: The specified video could not be found.

```json
{
  "error": {
    "code": 404,
    "message": "Video not found",
    "details": "No video exists with the provided video ID"
  }
}
```

### Rate Limit

**Status Code**: `429 Too Many Requests`

**Description**: You have exceeded your API rate limit.

```json
{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "You have exceeded your API quota. Please try again later.",
    "retryAfter": 3600
  }
}
```

### Service Unavailable

**Status Code**: `503 Service Unavailable`

**Description**: The similar videos service is temporarily unavailable.

```json
{
  "error": {
    "code": 503,
    "message": "Similar videos service unavailable",
    "details": "The video similarity service is temporarily unavailable. Please try again in a few minutes.",
    "retryAfter": 300
  }
}
```