Skip to main content
POST
/
api
/
v1
/
youtube
/
search
Search YouTube
curl --request POST \
  --url https://app.dumplingai.com/api/v1/youtube/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "<string>",
  "searchType": "videos",
  "maxResults": 25,
  "continuationToken": "<string>",
  "requestSource": "API"
}'
{
  "items": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "url": "<string>",
      "thumbnail": "<string>",
      "viewCountText": "<string>",
      "publishDateText": "<string>",
      "channel": {}
    }
  ],
  "continuationToken": "<string>"
}

Description

This endpoint searches YouTube and returns matching videos, channels, playlists, shorts, and other content types. Perfect for content discovery, research, and finding specific types of educational or business content.

Endpoint

POST https://app.dumplingai.com/api/v1/youtube/search

Headers

  • Content-Type: application/json
  • Authorization: Bearer <API_KEY> (required)

Request Body

{
  "query": "string", // Required. Search query
  "uploadDate": "string", // Optional. Filter by upload date
  "sortBy": "string", // Optional. Sort results
  "filter": "string", // Optional. Filter by content type
  "continuationToken": "string", // Optional. Token for pagination
  "includeExtras": "string" // Optional. Include additional metadata (slower response)
}

Accepted Values for uploadDate

ValueDescription
hourUploaded in the last hour
todayUploaded today
weekUploaded this week
monthUploaded this month
yearUploaded this year

Accepted Values for sortBy

ValueDescription
relevanceSort by relevance (default)
dateSort by upload date
viewCountSort by view count
ratingSort by rating

Accepted Values for filter

ValueDescription
videoVideos only
channelChannels only
playlistPlaylists only
shortShorts only
liveLive streams only
movieMovies only

Responses

Success (200)

Returns search results organized by content type with pagination support.
{
  "videos": [
    {
      "type": "video",
      "id": "Mus_vwhTCq0",
      "url": "https://www.youtube.com/watch?v=Mus_vwhTCq0",
      "title": "Full Stack Web Development Tutorial - Build a Complete App",
      "thumbnail": "https://i.ytimg.com/vi/Mus_vwhTCq0/hq720.jpg",
      "channel": {
        "id": "UCFbNIlppjAuEX4znoulh0Cw",
        "title": "Web Dev Simplified",
        "handle": "webdevsimplified",
        "thumbnail": "https://yt3.ggpht.com/ytc/AIdro_l3ee46SNWQDE..."
      },
      "viewCountText": "425,891 views",
      "viewCountInt": 425891,
      "publishedTimeText": "3 months ago",
      "publishedTime": "2024-10-15T17:08:46.499Z",
      "lengthText": "2:14:32",
      "lengthSeconds": 8072,
      "badges": ["4K", "CC"]
    }
  ],
  "channels": [
    {
      "type": "channel",
      "id": "UCWv7vMbMWH4-V0ZXdmDpPBA",
      "title": "Programming with Mosh",
      "handle": "programmingwithmosh",
      "thumbnail": "https://yt3.ggpht.com/ytc/AIdro_nBgMGIxgHeh...",
      "subscriberCountText": "3.2M subscribers",
      "description": "I train programmers through my online courses and YouTube channel..."
    }
  ],
  "shorts": [
    {
      "type": "short",
      "id": "dM-Q7WKqt8I",
      "url": "https://www.youtube.com/watch?v=dM-Q7WKqt8I",
      "title": "CSS Grid vs Flexbox in 60 seconds",
      "thumbnail": "https://i.ytimg.com/vi/dM-Q7WKqt8I/hq720.jpg",
      "channel": {
        "id": "UCFbNIlppjAuEX4znoulh0Cw",
        "title": "Web Dev Simplified",
        "handle": "webdevsimplified",
        "thumbnail": "https://yt3.ggpht.com/ytc/AIdro_l3ee46SNWQDE..."
      },
      "viewCountText": "89,432 views",
      "viewCountInt": 89432,
      "publishedTimeText": "2 weeks ago",
      "publishedTime": "2025-01-14T17:08:46.499Z",
      "lengthText": "0:58",
      "lengthSeconds": 58,
      "badges": []
    }
  ],
  "playlists": [
    {
      "type": "playlist",
      "id": "PLZlA0Gpn_vH_uZs4vJMIhcinABSTUH2bY",
      "title": "Complete React Tutorial Series",
      "thumbnail": "https://i.ytimg.com/vi/Mus_vwhTCq0/hqdefault.jpg",
      "channel": {
        "title": "Net Ninja",
        "id": "UCW5YeuERMmlnqo4oq8vwUpg"
      },
      "videoCount": 35
    }
  ],
  "shelves": [
    {
      "type": "shelf",
      "title": "Latest tutorials",
      "items": [
        {
          "type": "video",
          "id": "example123",
          "title": "React Hooks Tutorial",
          "thumbnail": "https://i.ytimg.com/vi/example123/hqdefault.jpg"
        }
      ]
    }
  ],
  "lives": [],
  "continuationToken": "EooDEg..."
}
  • Content-Type: application/json
  • X-RateLimit-Limit: The rate limit for the user
  • X-RateLimit-Remaining: The remaining number of requests for the user

Bad Request (400)

Returned if the request is invalid or missing required parameters.
{
  "error": "'query' parameter is required and must be a non-empty string. Please provide a search term."
}

Bad Gateway (502)

Returned if the external service is unavailable or returns invalid data.
{
  "error": "Failed to search YouTube"
}

Internal Server Error (500)

Returned if there’s an unexpected server error.
{
  "error": "An unexpected server error occurred while searching YouTube"
}

Example Request

curl -X POST https://app.dumplingai.com/api/v1/youtube/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "query": "web development tutorial",
  "filter": "video",
  "sortBy": "viewCount",
  "uploadDate": "month"
}'

Example Response

{
  "videos": [
    {
      "type": "video",
      "id": "Mus_vwhTCq0",
      "url": "https://www.youtube.com/watch?v=Mus_vwhTCq0",
      "title": "Full Stack Web Development Tutorial - Build a Complete App",
      "thumbnail": "https://i.ytimg.com/vi/Mus_vwhTCq0/hq720.jpg",
      "channel": {
        "id": "UCFbNIlppjAuEX4znoulh0Cw",
        "title": "Web Dev Simplified",
        "handle": "webdevsimplified",
        "thumbnail": "https://yt3.ggpht.com/ytc/AIdro_l3ee46SNWQDE3tpPXONvTIEN2ZFGF7DMRLSc4kPx1zhEQ=s68-c-k-c0x00ffffff-no-rj"
      },
      "viewCountText": "425,891 views",
      "viewCountInt": 425891,
      "publishedTimeText": "3 months ago",
      "publishedTime": "2024-10-15T17:08:46.499Z",
      "lengthText": "2:14:32",
      "lengthSeconds": 8072,
      "badges": ["4K", "CC"]
    }
  ],
  "channels": [],
  "playlists": [],
  "shorts": [],
  "shelves": [],
  "lives": [],
  "continuationToken": "EooDEg..."
}

Notes

  • The query parameter is required and must be a non-empty string
  • Use filters to narrow down results to specific content types (videos, channels, playlists, etc.)
  • The continuationToken from the response can be used to fetch additional pages of results
  • Setting includeExtras to “true” includes additional metadata like like/comment counts but may slow down the response
  • Search results are organized by content type in separate arrays
  • This endpoint uses 1 credit per request
  • Results are paginated - use the continuationToken to retrieve additional pages

Rate Limiting

Rate limit headers (X-RateLimit-Limit and X-RateLimit-Remaining) are included in the response to indicate the user’s current rate limit status.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
query
string
required
searchType
enum<string>
default:videos
Available options:
videos,
shorts,
channels
maxResults
integer
Required range: 1 <= x <= 50
continuationToken
string
requestSource
enum<string>

Optional identifier describing where the API request originated.

Available options:
API,
WEB,
MAKE_DOT_COM,
ZAPIER,
N8N,
PLAYGROUND,
DEFAULT_AUTOMATION,
AGENT_PREVIEW,
AGENT_LIVE,
AUTOPILOT,
STUDIO

Response

Search results returned.

items
object[]
continuationToken
string | null
I