---
title: "YouTube Search"
description: "The YouTube Search API searches live YouTube for videos, channels, playlists, and shorts. Results come straight from YouTube at request time — nothing is read from the NexLev catalog — which makes it the right tool when your workflow needs to know what YouTube is ranking right now."
source: "https://dashboard.nexlev.io/docs/n8n/youtube-search"
---

# YouTube Search

The YouTube Search API searches **live YouTube** for videos, channels, playlists, and shorts. Results come straight from YouTube at request time — nothing is read from the NexLev catalog — which makes it the right tool when your workflow needs to know what YouTube is ranking _right now_.

## Overview

Use this API to run a keyword search against YouTube and get back the videos, channels, playlists, and shorts YouTube currently returns, with optional filters for content type, duration, upload recency, video features, and region. Every result carries a `type` discriminator, and a single unfiltered page can mix all four types together.

> **Info**
>
> **Not to be confused with the catalog search.** NexLev's own indexed video
> catalog supports research filters such as outlier score, subscriber count, and
> RPM. Use this operation when you need current YouTube results; use the catalog
> when you need those curated filters.

## Quick Start

Get started in 3 simple steps:

1. **Install NexLev**: Add the NexLev node to your n8n instance ([Installation Guide](/docs/n8n/quickstart))
2. **Get API Key**: Create your API key at [API Key](https://dashboard.nexlev.io/nexlev-api/create-api-key)
3. **Make Your First Request**:
   - Add NexLev node → Select "YouTube Search" → Choose "Search"
   - Enter a Query (e.g., `mkbhd`)
   - Execute to get live YouTube results

**Example Result**: You'll receive a mixed set of videos, channels, playlists, and shorts, plus a `continuation` token for the next page.

### Endpoint Details

- **Resource**: YouTube Search
- **Operations**: Search | Custom API Call
- **Authentication**: Required ([API Key](https://dashboard.nexlev.io/nexlev-api/create-api-key))
- **Quota Cost**: 🥞 **1 quota** per request

### API Reference

> **Info**
>
> Full endpoint details, cURL examples, and response schemas live in the
> [YouTube Search API reference](/docs/api/youtube-search).

| Operation | Method & Path                      | Quota Cost |
| --------- | ---------------------------------- | ---------- |
| Search    | `GET /api/external/youtube/search` | 🥞 1       |

> **Warning**
>
> **Authentication Required** — see [Authentication](/docs/api/authentication)
> for the required header format and how to get an API key.

> **Warning**
>
> **20 requests per minute** per API key on this endpoint, on top of your plan
> quota. Add a **Wait** node between iterations in high-volume loops to stay
> under it.

## Configuration

### Parameters

Parameter names are **camelCase**. Unknown parameters are **rejected with a `400`** rather than silently ignored — so a typo or a snake_case name (`sort_by`, `upload_date`) fails loudly instead of returning unfiltered results. This differs from the `channels/*` operations, which use `id` and `sort_by`.

| Parameter    | Type   | Required | Description                                                                                            |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `query`      | string | Yes      | Search terms, e.g. `mkbhd`                                                                             |
| `type`       | string | No       | `video`, `channel`, `playlist`, `shorts`, `movie`, or `show`. Omit for a mixed result set              |
| `sortBy`     | string | No       | `relevance` (default), `popularity`, `rating`, `date`, or `views`                                      |
| `duration`   | string | No       | `short` (under 4 min), `medium` (4–20 min), `long` (over 20 min)                                       |
| `uploadDate` | string | No       | `hour`, `today`, `week`, `month`, or `year`                                                            |
| `features`   | string | No       | Comma-separated: `HD`, `subtitles`, `CCommons`, `3D`, `Live`, `4K`, `360`, `HDR`, `VR180`              |
| `geo`        | string | No       | ISO 3166-2 country code, e.g. `US`, `GB`, `IN`                                                         |
| `lang`       | string | No       | Locale, e.g. `en`, `gb`, `hi`                                                                          |
| `token`      | string | No       | Pagination token — the `continuation` value from the previous response. Leave empty for the first page |

### Setup Steps

**Step 1: Add NexLev Node**

- Add the **NexLev** node to your workflow
- See [Quickstart Guide](/docs/n8n/quickstart) for installation instructions

**Step 2: Configure Resource**

- Under **Resource**, select **YouTube Search**

**Step 3: Select Operation**

- Under **Operation**, select **Search**

**Step 4: Authentication**

- Under **Credential to connect with**, select your **NexLev account**
- If not configured, create one using your [API Key](https://dashboard.nexlev.io/nexlev-api/create-api-key)

**Step 5: Enter Query** ✅ Required

- In the **Query** field, enter your search terms (e.g., `cooking tutorials`)

**Step 6: Configure Optional Filters**

- **Type**: leave empty for mixed results, or pick one type to keep downstream nodes simple
- **Sort By**: `views` surfaces the biggest performers, `date` surfaces the freshest uploads
- **Duration** / **Upload Date**: narrow to a format and a recency window
- **Features**: comma-separated list, e.g. `HD,subtitles`
- **Geo** / **Lang**: change which regional results YouTube returns
- **Continuation Token**: leave empty for the first request; see [Pagination](#pagination)

### Execution

Click **Execute step** to run the search.

## Gotchas Worth Handling in Your Workflow

These are all consequences of what YouTube returns upstream:

1. **The fields differ by `type`.** Every item carries a `type` discriminator — branch on it in a **Switch** node before mapping fields, or downstream nodes will read `undefined`. Only `video` items carry the full set; see the [per-type schemas in the API reference](/docs/api/youtube-search#video).
2. **`viewCount` is not consistently typed.** It is a numeric **string** on `video` items (`"2643412"`) and a **number** on `shorts` items (`29000000`). Coerce with `Number($json.viewCount)` in a **Code** node before comparing or summing, otherwise a Filter node comparison silently misbehaves.
3. **`publishedTime` is a relative human string** — `"3 days ago"`, `"1 year ago"` — not a timestamp. You cannot sort or date-filter on it. Fetch [Video Content → Get Video Details](/docs/n8n/video-content) for an absolute date.
4. **`duration` is a display string** (`"12:49"`), not seconds. Parse it if you need arithmetic.
5. **Shorts thumbnails are frequently `[]`.** Fall back to `https://i.ytimg.com/vi/{{ $json.videoId }}/hqdefault.jpg`.
6. **Channel thumbnails may be protocol-relative** (`//yt3.ggpht.com/...`). Prefix with `https:` before passing to an HTTP Request or image node.
7. **Shorts items have no channel fields.** If you need the channel, look it up with the `videoId`.
8. **Page size is not fixed and not controllable** — there is no limit parameter. Pages range from ~20 to 80+ items. Never assume a page size; paginate instead.
9. **`estimatedResults` may be absent** on some responses. Guard before reading it.
10. **`type=movie` and `type=show`** are accepted but items still come back tagged as `video`, `shorts`, or `playlist` — there is no `movie` or `show` item type.

## Pagination

The response returns a `continuation` token when more results are available.

- Leave **Continuation Token** empty for the first request
- Pass the `continuation` value from the previous response for subsequent pages
- Stop when `continuation` is **`null`**
- **Resend the same Query and all the same filters** alongside the token — tokens are opaque and tied to the original query

> **Warning**
>
> Unlike the `channels/*` operations, which end pagination with an **empty
> string**, this operation ends with **`null`**. An `IF` node checking for `""`
> will loop forever — check for `null` (or truthiness) instead.

### Error Responses

> **Tip**
>
> Full error code reference: [YouTube Search — API Reference
> →](/docs/api/youtube-search#error-responses)

A `502` means the upstream YouTube data provider was unavailable. It is safe to retry — enable **Retry On Fail** on the NexLev node for this operation.

## Workflow Examples

### Example 1: Basic Keyword Search

**Difficulty**: Beginner | **Time**: 5 minutes | **Use Case**: Keyword research

1. Add a [Manual Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.manualworkflowtrigger/) node
2. Add the **NexLev** node:
   - Resource: **YouTube Search**
   - Operation: **Search**
   - Query: `cooking tutorials`
   - Type: **video**
   - Sort By: **views**
3. Add a **Code** node to extract `title`, `channelTitle`, and `viewCount`
4. Export to [Google Sheets](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.googlesheets/)

**Next Steps**: Add a type filter or split mixed results by type.

---

### Example 2: Splitting Mixed Results by Type

**Difficulty**: Beginner | **Time**: 10 minutes | **Use Case**: Handling unfiltered searches

1. Add a **NexLev** node with **Query** set and **Type** left empty
2. Add an **Item Lists** (or **Code**) node to split the `results` array into individual items
3. Add a **Switch** node keyed on `{{ $json.type }}` with outputs for `video`, `shorts`, `channel`, and `playlist`
4. Map each branch separately — only the `video` branch has `duration`, `publishedTime`, and `badges`

**Why this matters**: A single unfiltered page can contain all four types, and mapping them with one Set node produces empty columns.

---

### Example 3: Full Pagination Loop

**Difficulty**: Intermediate | **Time**: 15 minutes | **Use Case**: Complete result collection

1. Add a [Manual Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.manualworkflowtrigger/) node
2. Add the **NexLev** node (first request):
   - Resource: **YouTube Search**, Operation: **Search**
   - Query: your search terms, Type: **video**
   - Leave **Continuation Token** empty
3. Add a **Loop Over Items** node for pagination:
   - Extract `continuation` from the response
   - If it is not `null`, loop back to another **NexLev** node
4. Add a second **NexLev** node (inside the loop):
   - Same Query and same filters as step 2
   - **Continuation Token**: `{{ $json.continuation }}`
5. Add a **Wait** node (3 seconds) inside the loop to stay under 20 requests per minute
6. Add a **Code** node to aggregate results across pages
7. Export the complete collection

**Tip**: Each page costs 🥞 1 quota, so cap the loop iterations rather than paginating to exhaustion.

---

### Example 4: Weekly Rank Tracking

**Difficulty**: Intermediate | **Time**: 20 minutes | **Use Case**: Competitor monitoring

1. Add a [Schedule Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.scheduletrigger/) node set to weekly
2. Add the **NexLev** node:
   - Query: your target keyword, Type: **video**, Sort By: **relevance**
3. Add a **Code** node to capture each result's position, `videoId`, `title`, and `channelTitle`
4. Append rows to [Google Sheets](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.googlesheets/) with the run date
5. Add a **Code** node to compare against last week's rows and flag new entrants or dropped videos
6. Send a summary via **Slack** or **Email**

---

### Example 5: Advanced — Search to Full Channel Profile

**Difficulty**: Advanced | **Time**: 30 minutes | **Use Case**: Niche discovery pipeline

1. **Search**: YouTube Search with `type=channel` for your niche keyword
2. **Deduplicate**: Use a **Code** node to drop channel IDs you already track
3. **Enrich**: For each `channelId`, call [Channel Content → Get About](/docs/n8n/channel-content) for subscriber and view stats
4. **Analyze**: Call [Channel Analytics](/docs/n8n/channel-analytics) for revenue and geography data
5. **Filter**: Keep channels matching your criteria (e.g., under 100K subscribers, above-average RPM)
6. **Export**: Write the qualified list to your database or [Notion](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.notion/)

**Benefits**: Turns a single keyword into a filtered, enriched list of niche channels in one execution.

## Related Resources

- [Quickstart Guide](/docs/n8n/quickstart) - Learn how to set up NexLev with n8n
- [YouTube Search API Reference](/docs/api/youtube-search) - Full schemas and error codes
- [Channel Content](/docs/n8n/channel-content) - Fetch details, videos, shorts, and playlists for a channel you found
- [Video Content](/docs/n8n/video-content) - Absolute publish dates, transcripts, comments, and RPM for a `videoId`
- [Similar Channels](/docs/n8n/search-similar-channel) - Expand from one channel to its neighbors

## Best Practices

### Performance Optimization

- **Filter at the source**: Pass `type`, `duration`, and `uploadDate` rather than fetching mixed results and discarding them downstream — same quota cost, far less processing
- **Cap pagination**: Each page costs 🥞 **1 quota**. Decide how many pages you actually need before building the loop
- **Add a Wait node in loops**: The 20-requests-per-minute limit is enforced per API key across all your workflows
- **Cache by query**: Search results for the same query change slowly. Cache for a few hours rather than re-running per item

### Common Mistakes to Avoid

❌ **Don't**: Use snake_case parameter names like `sort_by` or `upload_date`
✅ **Do**: Use camelCase (`sortBy`, `uploadDate`) — unknown names return `400`

❌ **Don't**: Assume every item has `duration` or `publishedTime`
✅ **Do**: Branch on `type` first with a Switch node

❌ **Don't**: Compare `viewCount` directly in a Filter node
✅ **Do**: Coerce with `Number($json.viewCount)` — it is a string on videos and a number on shorts

❌ **Don't**: Check for an empty-string `continuation` to stop paginating
✅ **Do**: Check for `null`

❌ **Don't**: Change the query or filters while reusing a continuation token
✅ **Do**: Resend the identical query and filters, or start over

### Rate Limiting

- 20 requests per minute per API key on this endpoint
- If you receive a `429 Too Many Requests` error, wait for the time specified in `retryAfter`
- Consider exponential backoff for production workflows
- Distribute large batch searches over time rather than firing them in parallel

## Troubleshooting

### 400 error: "property ... should not exist"

**Problem**: The request was rejected for an unrecognized parameter name.

**Solutions**:

1. Check for snake_case names — this endpoint uses `sortBy` and `uploadDate`, not `sort_by` / `upload_date`
2. Check for parameter names borrowed from the `channels/*` operations (`id`, `forUsername`)
3. Read the `message` array in the response — it names every offending property

### Downstream nodes read `undefined`

**Problem**: Fields like `duration` or `channelTitle` are missing for some items.

**Solutions**:

1. You are looking at a mixed result set — only `video` items carry the full field set
2. Add a **Switch** node on `type` and map each branch separately
3. Or pass `type=video` so every item has the same shape

### Pagination loop never ends

**Problem**: The loop keeps running past the last page.

**Solutions**:

1. This endpoint returns `null` — not `""` — when there are no more pages
2. Use a truthiness check on `continuation` in your IF node
3. Add a maximum-iterations guard so a stuck loop cannot drain your quota

### 502 error

**Problem**: The upstream YouTube data provider was unavailable.

**Solutions**:

1. Retry — the error is transient, and both the primary and fallback providers had to fail to produce it
2. Enable **Retry On Fail** on the NexLev node
3. Check the `source` field on successful responses to see whether you are being served by the fallback path

## Support

If you encounter issues or have questions about the YouTube Search API, please contact our support team at [contact@nexlev.io](mailto:contact@nexlev.io) or refer to our troubleshooting guide.