YouTube Search API

Search live YouTube for videos, channels, playlists, and shorts. Results come straight from YouTube at request time — nothing is read from the NexLev catalog.

Base URL: https://prod.dashboard.nexlev.io — see Authentication. This operation costs 🥞 1 quota per request — see Rate Limits & Quota.

Requests are served with automatic failover across upstream data providers. The source field in every response reports whether the primary or the fallback path answered; the payload shape is identical either way.

Operations Quick Reference

Rate Limit

Search YouTube

GET /api/external/youtube/search

Description: Run a YouTube search and return the videos, channels, playlists, and shorts YouTube currently ranks for that query, with optional type, duration, recency, feature, and region filters.

When to use this operation:

• Checking what YouTube ranks for a keyword right now
• Keyword and title research against live search results
• Finding channels or playlists by name when you do not have a channel ID
• Sampling shorts for a topic without going channel by channel

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

Example URLs

https://prod.dashboard.nexlev.io/api/external/youtube/search?query=mkbhd
https://prod.dashboard.nexlev.io/api/external/youtube/search?query=mkbhd&type=video&sortBy=views

cURL Example:

curl "https://prod.dashboard.nexlev.io/api/external/youtube/search?query=mkbhd&type=video&sortBy=views" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status Code: 200 OK

Response Body:

{
  "query": "mkbhd",
  "estimatedResults": "360582",
  "continuation": "EpoDEgVta2JoZBqQA0VnSVFBVWdV...",
  "resultCount": 20,
  "source": "primary",
  "results": [
    {
      "type": "video",
      "videoId": "_xjxwl1zLMc",
      "title": "Framework 13 Pro: The Modular Laptop is Real!",
      "channelTitle": "Marques Brownlee",
      "channelId": "UCBJycsmduvYEL83R_U4JriQ",
      "channelHandle": "@mkbhd",
      "description": "The modular Macbook Pro for Linux users. Color me impressed...",
      "viewCount": "2643412",
      "publishedTime": "3 days ago",
      "duration": "12:49",
      "isLive": false,
      "badges": ["New", "4K"],
      "thumbnail": [
        {
          "url": "https://i.ytimg.com/vi/_xjxwl1zLMc/hq720.jpg?...",
          "width": 720,
          "height": 404
        },
        {
          "url": "https://i.ytimg.com/vi/_xjxwl1zLMc/hq720.jpg?...",
          "width": 360,
          "height": 202
        }
      ]
    }
  ],
  "filters": {
    "type": "video",
    "sortBy": "views"
  }
}

Envelope Fields

• query - The query that was executed
• estimatedResults - YouTube's own estimate of total matches, as a numeric string. May be absent on some responses — do not assume it is present
• continuation - Token for the next page. null means there are no further pages
• resultCount - Number of items in results for this page
• source - "primary" or "fallback"; which leg of the failover chain served the request. Informational only
• results - The result items. The shape varies by type — see below
• filters - Echo of the filters that were applied. Only type, sortBy, duration, uploadDate, and geo are echoed — features and lang are not. Filters you did not pass are omitted, not null, so this is {} for an unfiltered query

Result Item Shapes

Every item carries a type discriminator. Branch on it — the available fields differ significantly. Pick a type below for its fields and a sample payload.

{
  "type": "video",
  "videoId": "_xjxwl1zLMc",
  "title": "Framework 13 Pro: The Modular Laptop is Real!",
  "channelTitle": "Marques Brownlee",
  "channelId": "UCBJycsmduvYEL83R_U4JriQ",
  "channelHandle": "@mkbhd",
  "description": "The modular Macbook Pro for Linux users. Color me impressed...",
  "viewCount": "2643412",
  "publishedTime": "3 days ago",
  "duration": "12:49",
  "isLive": false,
  "badges": ["New", "4K"],
  "thumbnail": [
    {
      "url": "https://i.ytimg.com/vi/_xjxwl1zLMc/hq720.jpg?...",
      "width": 720,
      "height": 404
    }
  ]
}

{
  "type": "shorts",
  "videoId": "YHqpKFaFbyc",
  "title": "Tomahawk Steak Frites!🥩 @ChefRush",
  "viewCount": 29000000,
  "thumbnail": []
}

{
  "type": "channel",
  "title": "Marques Brownlee",
  "channelTitle": "Marques Brownlee",
  "channelId": "UCBJycsmduvYEL83R_U4JriQ",
  "channelHandle": "@mkbhd",
  "description": "MKBHD: Quality Tech Videos | YouTuber | Geek | ...",
  "thumbnail": [{ "url": "//yt3.ggpht.com/...", "width": 176, "height": 176 }]
}

{
  "type": "playlist",
  "title": "Tech Reviews 2025",
  "videoId": "_xjxwl1zLMc",
  "channelTitle": "Marques Brownlee",
  "channelId": "UCBJycsmduvYEL83R_U4JriQ",
  "channelHandle": "@mkbhd",
  "thumbnail": [
    {
      "url": "https://i.ytimg.com/vi/_xjxwl1zLMc/hqdefault.jpg",
      "width": 336,
      "height": 188
    }
  ]
}

Integration Notes

These are all consequences of what YouTube returns upstream — worth handling defensively:

1. viewCount is not consistently typed. It is a numeric string on video items ("2643412") and a number on shorts items (29000000). Coerce before doing arithmetic.
2. publishedTime is a relative human string, not a timestamp — "3 days ago", "1 year ago". There is no absolute date in the search payload; call Video Details if you need one.
3. duration is a display string ("12:49"), not seconds.
4. Shorts are flattened out of their shelf, and their thumbnail array is frequently empty — fall back to https://i.ytimg.com/vi/{videoId}/hqdefault.jpg.
5. Channel thumbnails may be protocol-relative (//yt3.ggpht.com/...). Prefix with https: before use.
6. Mixed results by default. Without type, a single page can contain videos, channels, playlists, and shorts together, and resultCount counts them all.
7. Result counts per page are not fixed and are not controllable — there is no limit parameter. Observed pages range from ~20 to 80+ items, depending on what YouTube returns and how many shorts got unpacked from their shelf. Paginate with token; never assume a page size.
8. type=movie and type=show are accepted and do return results, but items are tagged with the standard types above — movie comes back as video items, and show returns a mix of video, shorts, and playlist. There is no movie or show item type.

Pagination

When more results are available, the response returns a continuation token. Pass it back as token to fetch the next page.

How to use continuation tokens:

1. Make an initial request without token to get the first page
2. Check the continuation field in the response:
   • If it contains a token, more results are available
   • If it is null, you have reached the last page
3. To fetch the next page, repeat the request with token set to that value — and resend the same query and all the same filters
4. Repeat until continuation is null

Example pagination workflow:

# page 1
curl "https://prod.dashboard.nexlev.io/api/external/youtube/search?query=cooking%20tutorials&type=video" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: {
  "continuation": "EpoDEgVta2JoZBqQA0VnSVFBVWdV...",
  "resultCount": 20,
  "results": [
    /* Array of result items */
  ]
}

# page 2 — feed `continuation` back in as `token`
curl "https://prod.dashboard.nexlev.io/api/external/youtube/search?query=cooking%20tutorials&type=video&token=EpoDEgVta2JoZBqQA0VnSVFBVWdV..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: {
  "continuation": null,  // null means no more results
  "resultCount": 18,
  "results": [
    /* Array of remaining result items */
  ]
}

Error Responses

{
  "success": false,
  "statusCode": 400,
  "message": [
    "property sort_by should not exist",
    "property upload_date should not exist"
  ],
  "error": "Bad Request",
  "path": "/api/external/youtube/search?query=x&sort_by=date&upload_date=week"
}

{
  "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"
  }
}

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

{
  "error": {
    "code": 502,
    "message": "Upstream provider unavailable",
    "details": "The YouTube data provider did not respond. Please retry."
  }
}

More Examples

# Most-viewed videos for a term
curl "https://prod.dashboard.nexlev.io/api/external/youtube/search?query=mkbhd&type=video&sortBy=views" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Channels only
curl "https://prod.dashboard.nexlev.io/api/external/youtube/search?query=mkbhd&type=channel" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Shorts, US region
curl "https://prod.dashboard.nexlev.io/api/external/youtube/search?query=cooking&type=shorts&geo=US&lang=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Short, recent, HD videos with subtitles
curl "https://prod.dashboard.nexlev.io/api/external/youtube/search?query=news&type=video&duration=short&uploadDate=week&features=HD,subtitles" \
  -H "Authorization: Bearer YOUR_API_KEY"

Related Endpoints