YouTube Search Endpoint
Search YouTube and return normalized video results.
Getting Started
Send your API key as a bearer token. Start with the smallest request below.
Run YouTube Search
Send the smallest useful request and read the structured response.
curl -X POST "https://api.datablue.dev/v1/data/youtube/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "python web scraping tutorial 2026",
"limit": 5,
"max_pages": 5,
"country": "us",
"language": "en"
}'Example response
{
"success": true,
"time_taken": 2.87,
"query": "python web scraping tutorial 2026",
"count": 5,
"complete": false,
"stop_reason": "return_limit_reached",
"pages_fetched": 1,
"next_cursor": "dbyt1.eyJraW5kIjoic2VhcmNoIn0.signature",
"scanned_count": 20,
"matched_count": 20,
"duplicate_count": 0,
"results": [
{
"video_id": "xyz789abc123",
"title": "Python Web Scraping Full Course 2026 - BeautifulSoup, Selenium, Playwright",
"url": "https://www.youtube.com/watch?v=xyz789abc123",
"channel": "Tech With Tim",
"channel_id": "UC4JX40jDee_tINbkjycV4Sg",
"views": 890000,
"views_text": "890K views",
"views_count_status": "rounded",
"published": "1 month ago",
"duration": "3:42:15",
"duration_seconds": 13335,
"thumbnail": "https://i.ytimg.com/vi/xyz789abc123/maxresdefault.jpg",
"description": "Learn web scraping from scratch with Python...",
"badges": [
"New"
]
}
]
}Options
Query and Target
Set the search term, identifier, or source URL that defines the request.
curl -X POST "https://api.datablue.dev/v1/data/youtube/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "web scraping tools",
"limit": 5,
"max_pages": 5,
"country": "us",
"language": "en"
}'Example response
{
"success": true,
"time_taken": 2.87,
"query": "python web scraping tutorial 2026",
"count": 5,
"complete": false,
"stop_reason": "return_limit_reached",
"pages_fetched": 1,
"next_cursor": "dbyt1.eyJraW5kIjoic2VhcmNoIn0.signature",
"scanned_count": 20,
"matched_count": 20,
"duplicate_count": 0,
"results": [
{
"video_id": "xyz789abc123",
"title": "Python Web Scraping Full Course 2026 - BeautifulSoup, Selenium, Playwright",
"url": "https://www.youtube.com/watch?v=xyz789abc123",
"channel": "Tech With Tim",
"channel_id": "UC4JX40jDee_tINbkjycV4Sg",
"views": 890000,
"views_text": "890K views",
"views_count_status": "rounded",
"published": "1 month ago",
"duration": "3:42:15"
}
]
}Results and Pagination
Control how many records or pages are returned.
curl -X POST "https://api.datablue.dev/v1/data/youtube/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "python web scraping tutorial 2026",
"limit": 20,
"max_pages": 10,
"country": "us",
"language": "en",
"cursor": "example"
}'Example response
{
"success": true,
"time_taken": 2.87,
"query": "python web scraping tutorial 2026",
"count": 5,
"complete": false,
"stop_reason": "return_limit_reached",
"pages_fetched": 1,
"next_cursor": "dbyt1.eyJraW5kIjoic2VhcmNoIn0.signature",
"scanned_count": 20,
"matched_count": 20,
"duplicate_count": 0,
"results": [
{
"video_id": "xyz789abc123",
"title": "Python Web Scraping Full Course 2026 - BeautifulSoup, Selenium, Playwright",
"url": "https://www.youtube.com/watch?v=xyz789abc123",
"channel": "Tech With Tim",
"channel_id": "UC4JX40jDee_tINbkjycV4Sg",
"views": 890000,
"views_text": "890K views",
"views_count_status": "rounded",
"published": "1 month ago",
"duration": "3:42:15"
}
]
}Location and Language
Localize results with country, language, coordinates, or delivery-location fields.
curl -X POST "https://api.datablue.dev/v1/data/youtube/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "python web scraping tutorial 2026",
"limit": 5,
"max_pages": 5,
"country": "in",
"language": "en"
}'Example response
{
"success": true,
"time_taken": 2.87,
"query": "python web scraping tutorial 2026",
"count": 5,
"complete": false,
"stop_reason": "return_limit_reached",
"pages_fetched": 1,
"next_cursor": "dbyt1.eyJraW5kIjoic2VhcmNoIn0.signature",
"scanned_count": 20,
"matched_count": 20,
"duplicate_count": 0,
"results": [
{
"video_id": "xyz789abc123",
"title": "Python Web Scraping Full Course 2026 - BeautifulSoup, Selenium, Playwright",
"url": "https://www.youtube.com/watch?v=xyz789abc123",
"channel": "Tech With Tim",
"channel_id": "UC4JX40jDee_tINbkjycV4Sg",
"views": 890000,
"views_text": "890K views",
"views_count_status": "rounded",
"published": "1 month ago",
"duration": "3:42:15"
}
]
}Additional Options
Set endpoint-specific options for this request.
curl -X POST "https://api.datablue.dev/v1/data/youtube/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "python web scraping tutorial 2026",
"limit": 5,
"max_pages": 5,
"country": "us",
"language": "en",
"sp": "example"
}'Example response
{
"success": true,
"time_taken": 2.87,
"query": "python web scraping tutorial 2026",
"count": 5,
"complete": false,
"stop_reason": "return_limit_reached",
"pages_fetched": 1,
"next_cursor": "dbyt1.eyJraW5kIjoic2VhcmNoIn0.signature",
"scanned_count": 20,
"matched_count": 20,
"duplicate_count": 0,
"results": [
{
"video_id": "xyz789abc123",
"title": "Python Web Scraping Full Course 2026 - BeautifulSoup, Selenium, Playwright",
"url": "https://www.youtube.com/watch?v=xyz789abc123",
"channel": "Tech With Tim",
"channel_id": "UC4JX40jDee_tINbkjycV4Sg",
"views": 890000,
"views_text": "890K views",
"views_count_status": "rounded",
"published": "1 month ago",
"duration": "3:42:15"
}
]
}Response
Read success first, then consume the endpoint-specific records and pagination fields shown below.
Error Handling
Handle 401 for authentication, 422 for invalid input, 429 for limits, and retry only transient failures.