> ## Documentation Index > Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt > Use this file to discover all available pages before exploring further. # Search > Searches YouTube and returns what its search shows, in its order: videos, Shorts, live streams, channels (an artist's card included) and playlists (Mixes and podcasts included), about 20–60 per page. Narrow it like YouTube's own filters: by upload date, by type (videos, Shorts, channels or playlists), by length (videos only), and sort by popularity instead of relevance; and pick the country to search from with `region`. Videos come with their title, link, description snippet, views, upload time, length, badges, channel and thumbnails; live streams with how many are watching; Shorts with their title, views, cover and first frame; channels with their handle, avatar, subscribers and verified / official-artist badge; playlists with their owner, video count and first video. Results shown in a shelf ("Shorts", "Latest from …", an artist's card) say which. When YouTube corrects a misspelt query, `showingResultsFor` says what it searched instead. Pass the returned `cursor` back (with the same query) for the next page. Only publicly available data is returned. > [!NOTE] > > **Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free. > [accordion] Copy for AI assistant > > Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button). > > ```text Prompt > I want to make an API call to /v1/youtube/search. Here are the details: > > Endpoint: GET https://api.scraperize.com/v1/youtube/search > Description: Searches YouTube and returns what its search shows, in its order: videos, Shorts, live streams, channels (an artist's card included) and playlists (Mixes and podcasts included), about 20–60 per page. Narrow it like YouTube's own filters: by upload date, by type (videos, Shorts, channels or playlists), by length (videos only), and sort by popularity instead of relevance; and pick the country to search from with `region`. Videos come with their title, link, description snippet, views, upload time, length, badges, channel and thumbnails; live streams with how many are watching; Shorts with their title, views, cover and first frame; channels with their handle, avatar, subscribers and verified / official-artist badge; playlists with their owner, video count and first video. Results shown in a shelf ("Shorts", "Latest from …", an artist's card) say which. When YouTube corrects a misspelt query, `showingResultsFor` says what it searched instead. Pass the returned `cursor` back (with the same query) for the next page. Only publicly available data is returned. > > Required Headers: > - x-api-key: Your API key > > Parameters: > - query (string) [required]: What to search for. > - uploadDate (select): Only results uploaded in this period. Not for `type=channels` or `type=playlists`. > - sortBy (select): `relevance` (default) or `popular` (most viewed first). > - type (select): Only this kind of result. Omit for everything YouTube shows. > - duration (select): Only videos of this length. Videos only: use it without `type` or with `type=videos`. > - region (select): The country to search from, as a two-letter code (ISO 3166-1) — YouTube ranks results for the viewer's country. Omit for the default. > - cursor (string): The `cursor` from the previous page, to get the next one (it keeps the filters and region). Omit for the first page. > - cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh. > > Example Response: > { > "data": { > "query": "lofi hip hop", > "region": null, > "filters": { > "uploadDate": null, > "sortBy": "relevance", > "type": null, > "duration": null > }, > "showingResultsFor": null, > "includingResultsFor": null, > "hashtag": null, > "estimatedResults": 11370869, > "results": [ > { > "type": "playlist", > "kind": "mix", > "id": "RDATfmbG9maSBoaXAgaG9w", > "url": "https://www.youtube.com/playlist?list=RDATfmbG9maSBoaXAgaG9w", > "title": "Mix • Lofi hip hop", > "videoCount": null, > "channelName": "Академия глубокой релаксации, Kudasaibeats, RŮDE, and more", > "channelId": null, > "firstVideoId": "R8om0QifqII", > "thumbnailUrl": "https://i.ytimg.com/vi/R8om0QifqII/hqdefault.jpg?sqp=-oaymwEXCOADEI4CSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBN0ePqpHQrvDXXKRJL_9Fgj53naQ", > "thumbnails": [ > { > "url": "https://i.ytimg.com/vi/R8om0QifqII/hqdefault.jpg?sqp=-oaymwEXCOADEI4CSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBN0ePqpHQrvDXXKRJL_9Fgj53naQ", > "width": 480, > "height": 270 > } > ], > "position": 1, > "shelfTitle": null > } > ], > "counts": { > "video": 14, > "short": 25, > "live": 5, > "channel": 0, > "playlist": 1 > }, > "count": 45, > "cursor": "eyJrIjoibG9maSBoaXAgaG9wIiwiYyI6IkVxMERFZ3hzYjJacElHaHBjQ0JvYjNBYW5BTlRRbE5EUVZKYVUxSkZSbFZhYlRGcFVucHNkRmxXVGtOaU1rWlpVVmRrYUZKNmJETm5aMFZNWW1wWmVGWlZlRVpXVkdS…", > "hasMore": true, > "fetchedAt": "2026-11-05T19:15:07.802Z" > }, > "meta": { > "requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f", > "creditsCharged": 1, > "creditsRemaining": 4999, > "cached": false > } > } > > Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices. > ``` ## OpenAPI ````yaml /api-reference/openapi.json get /v1/youtube/search openapi: 3.0.3 info: title: Scraperize API version: 1.0.0 description: >- Extract public data from social media platforms as clean JSON. Endpoints are split by platform and by what they return, e.g. `GET /v1/twitter/tweet`. ## Authentication Send your API key in the `x-api-key` header (or `Authorization: Bearer `). Create keys in your dashboard. ## Credits Each successful live scrape costs **1 credit**. Credits are prepaid and never expire. ## Caching Every endpoint accepts an optional `cache_max_age` (`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for **0 credits**. ## Responses Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return `{ "error": { "code", "message", "requestId" } }` with a matching HTTP status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`, `cached`, and (on a hit) `cachedAt`. ## Rate limits Requests are limited per team per minute; over the limit returns `429` with a `Retry-After` header. servers: - url: https://api.scraperize.com description: Production security: - ApiKeyAuth: [] tags: - name: Twitter description: Twitter / X scraping endpoints - name: Facebook description: Facebook scraping endpoints - name: Linkme description: Linkme (link.me) scraping endpoints - name: Amazon description: Amazon (creator shop / storefront) scraping endpoints - name: Linkbio description: Linkbio (lnk.bio) scraping endpoints - name: Pillar description: Pillar (pillar.io) scraping endpoints - name: Komi description: Komi (komi.io) scraping endpoints - name: Linktree description: Linktree (linktr.ee) scraping endpoints - name: Kick description: Kick (kick.com) scraping endpoints - name: Snapchat description: Snapchat (snapchat.com) scraping endpoints - name: Telegram description: Telegram (t.me) scraping endpoints - name: LinkedIn description: LinkedIn scraping endpoints - name: Twitch description: Twitch scraping endpoints - name: TikTok description: TikTok (tiktok.com) scraping endpoints - name: Instagram description: Instagram scraping endpoints - name: Lagos Life description: Lagos Life scraping endpoints - name: Bluesky description: Bluesky (bsky.app) scraping endpoints - name: Threads description: Threads (threads.com) scraping endpoints - name: Reddit description: Reddit (reddit.com) scraping endpoints - name: Rumble description: Rumble (rumble.com) scraping endpoints - name: Truth Social description: Truth Social (truthsocial.com) scraping endpoints - name: YouTube description: YouTube (youtube.com) scraping endpoints paths: /v1/youtube/search: get: tags: - YouTube summary: Search description: >- Searches YouTube and returns what its search shows, in its order: videos, Shorts, live streams, channels (an artist's card included) and playlists (Mixes and podcasts included), about 20–60 per page. Narrow it like YouTube's own filters: by upload date, by type (videos, Shorts, channels or playlists), by length (videos only), and sort by popularity instead of relevance; and pick the country to search from with `region`. Videos come with their title, link, description snippet, views, upload time, length, badges, channel and thumbnails; live streams with how many are watching; Shorts with their title, views, cover and first frame; channels with their handle, avatar, subscribers and verified / official-artist badge; playlists with their owner, video count and first video. Results shown in a shelf ("Shorts", "Latest from …", an artist's card) say which. When YouTube corrects a misspelt query, `showingResultsFor` says what it searched instead. Pass the returned `cursor` back (with the same query) for the next page. Only publicly available data is returned. parameters: - name: query in: query required: true description: What to search for. schema: type: string example: lofi hip hop - name: uploadDate in: query required: false description: >- Only results uploaded in this period. Not for `type=channels` or `type=playlists`. schema: type: string enum: - today - this-week - this-month - this-year - name: sortBy in: query required: false description: '`relevance` (default) or `popular` (most viewed first).' schema: type: string enum: - relevance - popular default: relevance - name: type in: query required: false description: Only this kind of result. Omit for everything YouTube shows. schema: type: string enum: - videos - shorts - channels - playlists - name: duration in: query required: false description: >- Only videos of this length. Videos only: use it without `type` or with `type=videos`. schema: type: string enum: - under-3-min - between-3-and-20-min - over-20-min - name: region in: query required: false description: >- The country to search from, as a two-letter code (ISO 3166-1) — YouTube ranks results for the viewer's country. Omit for the default. schema: type: string enum: - AL - DZ - AR - AU - AT - AZ - BY - BE - BO - BR - KH - CM - CA - CL - CO - CR - CZ - EG - FR - DE - GH - GR - HK - IS - IE - IL - IT - JM - JP - KZ - KE - KW - LI - LT - LU - MX - MA - MZ - NA - NL - NG - MK - 'NO' - PA - PE - PH - PT - PR - RO - SA - SG - ZA - KR - ES - SE - CH - TW - TH - TT - TN - TR - UG - UA - AE - GB - US - UY - UZ - VE x-enumNames: - Albania (AL) - Algeria (DZ) - Argentina (AR) - Australia (AU) - Austria (AT) - Azerbaijan (AZ) - Belarus (BY) - Belgium (BE) - Bolivia (BO) - Brazil (BR) - Cambodia (KH) - Cameroon (CM) - Canada (CA) - Chile (CL) - Colombia (CO) - Costa Rica (CR) - Czechia (CZ) - Egypt (EG) - France (FR) - Germany (DE) - Ghana (GH) - Greece (GR) - Hong Kong (HK) - Iceland (IS) - Ireland (IE) - Israel (IL) - Italy (IT) - Jamaica (JM) - Japan (JP) - Kazakhstan (KZ) - Kenya (KE) - Kuwait (KW) - Liechtenstein (LI) - Lithuania (LT) - Luxembourg (LU) - Mexico (MX) - Morocco (MA) - Mozambique (MZ) - Namibia (NA) - Netherlands (NL) - Nigeria (NG) - North Macedonia (MK) - Norway (NO) - Panama (PA) - Peru (PE) - Philippines (PH) - Portugal (PT) - Puerto Rico (PR) - Romania (RO) - Saudi Arabia (SA) - Singapore (SG) - South Africa (ZA) - South Korea (KR) - Spain (ES) - Sweden (SE) - Switzerland (CH) - Taiwan (TW) - Thailand (TH) - Trinidad and Tobago (TT) - Tunisia (TN) - Türkiye (TR) - Uganda (UG) - Ukraine (UA) - United Arab Emirates (AE) - United Kingdom (GB) - United States (US) - Uruguay (UY) - Uzbekistan (UZ) - Venezuela (VE) - name: cursor in: query required: false description: >- The `cursor` from the previous page, to get the next one (it keeps the filters and region). Omit for the first page. schema: type: string - name: cache_max_age in: query required: false description: >- Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh. schema: type: string enum: - 1d - 3d - 7d - 14d - 30d example: 7d responses: '200': description: One page of results (empty when nothing matches). content: application/json: schema: type: object properties: data: type: object properties: query: type: string region: type: string nullable: true filters: type: object showingResultsFor: type: string nullable: true includingResultsFor: type: string nullable: true hashtag: type: object nullable: true estimatedResults: type: integer nullable: true results: type: array items: type: object counts: type: object count: type: integer cursor: type: string nullable: true hasMore: type: boolean fetchedAt: type: string format: date-time meta: type: object description: >- requestId + credit/caching metadata (creditsCharged, creditsRemaining, cached, cachedAt). required: - data - meta example: data: query: lofi hip hop region: null filters: uploadDate: null sortBy: relevance type: null duration: null showingResultsFor: null includingResultsFor: null hashtag: null estimatedResults: 11370869 results: - type: playlist kind: mix id: RDATfmbG9maSBoaXAgaG9w url: >- https://www.youtube.com/playlist?list=RDATfmbG9maSBoaXAgaG9w title: Mix • Lofi hip hop videoCount: null channelName: >- Академия глубокой релаксации, Kudasaibeats, RŮDE, and more channelId: null firstVideoId: R8om0QifqII thumbnailUrl: >- https://i.ytimg.com/vi/R8om0QifqII/hqdefault.jpg?sqp=-oaymwEXCOADEI4CSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBN0ePqpHQrvDXXKRJL_9Fgj53naQ thumbnails: - url: >- https://i.ytimg.com/vi/R8om0QifqII/hqdefault.jpg?sqp=-oaymwEXCOADEI4CSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBN0ePqpHQrvDXXKRJL_9Fgj53naQ width: 480 height: 270 position: 1 shelfTitle: null - type: video id: n61ULEU7CO0 url: https://www.youtube.com/watch?v=n61ULEU7CO0 title: Best of lofi hip hop 2021 ✨ [beats to relax/study to] descriptionSnippet: "Listen on Spotify, Apple music and more → https://fanlink.tv/BestofLofi2021 The new Lofi Girl compilation “Best of 2021” is out now\_..." viewCount: 58551430 viewCountText: 58,551,430 views concurrentViewers: null publishedText: 4 years ago wasLive: false durationSeconds: 22258 durationText: '6:10:58' badges: - 1 product channelId: UCSJ4gkVC6NrvII8umztf0Ow channelName: Lofi Girl channelHandle: null isChannelVerified: true thumbnailUrl: >- https://i.ytimg.com/vi/n61ULEU7CO0/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAi4TCpAtbxLFIBULRlcZHudl1uFw thumbnails: - url: >- https://i.ytimg.com/vi/n61ULEU7CO0/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAi4TCpAtbxLFIBULRlcZHudl1uFw width: 720 height: 404 - url: >- https://i.ytimg.com/vi/n61ULEU7CO0/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBsbMTx1evh72jfc4JDtfDXYVhYNg width: 360 height: 202 previewUrl: >- https://i.ytimg.com/an_webp/n61ULEU7CO0/mqdefault_6s.webp?du=3000&sqp=CICLs9cG&rs=AOn4CLBirO-GQGnSLhV-m_dz0O2g1dEFRQ frameUrl: null collaborators: [] position: 2 shelfTitle: null - type: live id: rFZHOHl-L8A url: https://www.youtube.com/watch?v=rFZHOHl-L8A title: lofi hip hop radio 📚 beats to relax/study to descriptionSnippet: "Spooky season is officially upon us 2026 Halloween playlist available now: https://lnk.to/halloween-lofi02 | Listen on Spotify,\_..." viewCount: null viewCountText: 10,197 watching concurrentViewers: 10197 publishedText: null wasLive: false durationSeconds: null durationText: null badges: - LIVE - 24 products channelId: UCSJ4gkVC6NrvII8umztf0Ow channelName: Lofi Girl channelHandle: null isChannelVerified: true thumbnailUrl: >- https://i.ytimg.com/vi/rFZHOHl-L8A/hq720.jpg?v=6ad62bed&sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLCdekX1ygqqUJynjbliA5ayfR7tlw thumbnails: - url: >- https://i.ytimg.com/vi/rFZHOHl-L8A/hq720.jpg?v=6ad62bed&sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLCdekX1ygqqUJynjbliA5ayfR7tlw width: 720 height: 404 - url: >- https://i.ytimg.com/vi/rFZHOHl-L8A/hq720.jpg?v=6ad62bed&sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLDN3Yy-Dw3B9x_HYcTaGXq7gEVppA width: 360 height: 202 previewUrl: null frameUrl: null collaborators: [] position: 3 shelfTitle: null counts: video: 14 short: 25 live: 5 channel: 0 playlist: 1 count: 45 cursor: >- eyJrIjoibG9maSBoaXAgaG9wIiwiYyI6IkVxMERFZ3hzYjJacElHaHBjQ0JvYjNBYW5BTlRRbE5EUVZKYVUxSkZSbFZhYlRGcFVucHNkRmxXVGtOaU1rWlpVVmRrYUZKNmJETm5aMFZNWW1wWmVGWlZlRVpXVkdSRVZIcERRMEZSZEhsU2JIQkpWREJvYzB4VmR6UlJXVWxDUXpCT1RWcFdjRFZUVld4RlQxVktkbWRuUlV4UldGb3hXakprU2xNeFRrVlNSVmREUVZGMGMxWkdTbkJrVlZwS1ZqRlpNVTVKU1VKRE1FbzFWMnRrTVUxcVNUVk1XR3hDWjJkRlRGRllTbkpOVjJoeFlVWkdUbVZJVDBOQlVYUTJWbnBXTTJORmNGcE5XRXB1VlZsSlFrTXdUa2RTTUhoMlZWVnNiMkpYT1ROblowVk1Zekl3TWxOdFNrOU9WM1JvVjIwdFEwRlJkSGxoU0VwRVVucENWMlJJWjNwYU5FbENRM3BPVVZKcmJ6VlZNRlpWVlhwU1RtZG5SVXhPTURWUVZUQlNURmxxUWtsaVJsZERRVkYwVlZVd1JUSlNNRkUxVkZkc2RsUlpTVUpETWxJeFl6SmFkRlJHT1dsaVZFWjJaMmRGVEUxVmJ6QlpWR3hxVmtSS2MyRXpaVU5CVVhNMVZGUlNjVmR1Vm5oYVNHTjNUa2xKUWtNelRrZFBSRUpLVEZaU1VtRldZM2RuWjBWTVlsVmplRmxYVmtWT01qbHJZMWQxZVVGUldVdENRV2RYUlVGTWNVRlJVVWxCYUVGYUdJSGc2QmdpQzNObFlYSmphQzFtWldWayIsImYiOnsidXBsb2FkRGF0ZSI6bnVsbCwic29ydEJ5IjoicmVsZXZhbmNlIiwidHlwZSI6bnVsbCwiZHVyYXRpb24iOm51bGx9LCJyIjpudWxsfQ hasMore: true fetchedAt: '2026-11-05T19:15:07.802Z' meta: requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f creditsCharged: 1 creditsRemaining: 4999 cached: false '400': description: Invalid or expired cursor (or one for another query). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: BAD_REQUEST message: The request was invalid. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: API key required — pass it in the `x-api-key` header. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '402': description: Not enough credits for this request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INSUFFICIENT_CREDITS message: >- This request costs 1 credit, but your balance is 0. Top up to continue. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '422': description: >- Invalid query parameters (query is required; a filter value YouTube doesn't have, or a combination it can't do). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Request validation failed requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f details: - path: url message: url is required '429': description: Over the per-minute rate limit — honour `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: >- Rate limit exceeded — max 100 requests per 60s. Retry in ~30s. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f '503': description: >- Temporarily unavailable — retry after `Retry-After`. `error.code` tells you why: `UPSTREAM_BLOCKED` (the source blocked this request), `EXTRACTION_FAILED` (the source returned unexpected data), `PLATFORM_UNAVAILABLE` (the source is down), or `SERVICE_UNAVAILABLE` (we are at capacity). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UPSTREAM_BLOCKED message: >- The source is temporarily unavailable. Please try again shortly. requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f components: schemas: Error: type: object properties: error: type: object properties: code: type: string example: NOT_FOUND message: type: string example: The requested content was not found. requestId: type: string example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f details: type: array items: type: object description: Present on validation errors. required: - code - message - requestId required: - error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your API key. Send it in the `x-api-key` header (or `Authorization: Bearer `). Create and manage keys from your dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.