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.

Quick Start

Get started in 3 simple steps:

1. Install NexLev: Add the NexLev node to your n8n instance (Installation Guide)
2. Get API Key: Create your API key at 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)
• Quota Cost: 🥞 1 quota per request

API Reference

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.

Setup Steps

Step 1: Add NexLev Node

• Add the NexLev node to your workflow
• See Quickstart Guide 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

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

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.
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 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

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 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

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 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 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 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 for subscriber and view stats
4. Analyze: Call 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

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

Related Resources

• Quickstart Guide - Learn how to set up NexLev with n8n
• YouTube Search API Reference - Full schemas and error codes
• Channel Content - Fetch details, videos, shorts, and playlists for a channel you found
• Video Content - Absolute publish dates, transcripts, comments, and RPM for a videoId
• Similar Channels - 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 or refer to our troubleshooting guide.