YouTube search — POST /v1/youtube/search

YouTube's own InnerTube search call, without a browser (~0.5-1.2 MB, ~0.6 s). videos carry the id, title, channel (id, handle, verified badge), exact views when YouTube prints them exactly (views_text always, verbatim), the relative published_time verbatim, length and length_seconds, the description snippet and YouTube's badges ("4K", "CC", "LIVE", "New") verbatim; live rows carry watching. shorts, channels and playlists (incl. courses) come in their own arrays. Anything else on the page — ads, shelves, promos — is counted in skipped_items by renderer name, never mixed in. Filters are encoded as YouTube's own sp; next_page_token pages on (send it with q only). An empty page is not charged.

Request

POSThttps://api.scrapercompany.com/v1/youtube/search

Authenticate with your API key in the x-api-key header (see Authentication).

Body

JSON object. Unknown fields are rejected with 422.

qstringrequiredmin length 1, max length 500
Search query, as typed in YouTube's box.
page_tokenstring | nullmax length 4000
next_page_token from the previous answer of this route. It carries the query and the filters/sort, so send it alone (with q for search).
typestring | null
Result type filter (YouTube's Type menu). Omit for the mixed page.
One ofvideochannelplaylistmovieshorts
upload_datestring | null
Upload date filter. today/week/month/year are YouTube's menu values; hour is no longer in the menu but was verified to filter.
One ofhourtodayweekmonthyear
durationstring | null
Length filter, YouTube's buckets: short under 3 minutes, medium 3-20 minutes, long over 20 minutes.
One ofshortmediumlong
featuresarray of stringmax items 11
Feature filters (YouTube's Features menu), combined with AND. subtitles keeps videos with creator captions.
sortstring | null
YouTube's Prioritize menu: relevance (the default) or popularity (most viewed first). Upload-date and rating sorts are no longer honoured by YouTube and are refused.
One ofrelevancepopularity
spstring | nullmax length 200
Raw sp= value copied from a YouTube search URL, instead of type/upload_date/duration/features/sort.
hlstringdefault enpattern ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,4})?$
Interface language YouTube localizes texts in (hl): relative dates, view-count wording, caption track names. Counts parse to integers only for English-style numbers.
glstringdefault USpattern ^[A-Za-z]{2}$
Content country (gl), two letters.

Example request

curl -X POST "https://api.scrapercompany.com/v1/youtube/search" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "python tutorial"
  }'

Response

200 — One page of YouTube results, split by kind. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

200 response

{
  "search_parameters": {
    "engine": "youtube",
    "q": "python tutorial",
    "hl": "en",
    "gl": "US"
  },
  "search_information": {
    "estimated_results": 11103091,
    "total": 4
  },
  "videos": [
    {
      "position": 1,
      "video_id": "ix9cRaBkVe0",
      "title": "Python Full Course for free 🐍",
      "link": "https://www.youtube.com/watch?v=ix9cRaBkVe0",
      "channel": {
        "name": "Bro Code",
        "id": "UC4SVo0Ue36XCfOyb5Lh1viQ",
        "handle": "@BroCodez",
        "link": "https://www.youtube.com/@BroCodez",
        "verified": true,
        "thumbnail": "https://yt3.ggpht.com/ytc/AIdro_mPFVsxROj1dOtTWc9iNBwDYV4z42Q8LPokBSewiW9pCSg=s68-c-k-c0x00ffffff-no-rj"
      },
      "views": 12753881,
      "views_text": "12,753,881 views",
      "published_time": "2 years ago",
      "length": "12:00:00",
      "length_seconds": 43200,
      "description": "python #tutorial #beginners Python tutorial for beginners' full course 2024 *Learn Python in 1 HOUR* ...",
      "badges": [
        "Fundraiser"
      ],
      "is_live": false,
      "thumbnail": "https://i.ytimg.com/vi/ix9cRaBkVe0/hq720.jpg?sqp=-oaymwEnCNAFEJQDSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLDsLPZCX5PFS2a-Wng9IwGAduPqOQ"
    }
  ],
  "shorts": [
    {
      "position": 1,
      "video_id": "nluUYtejoIE",
      "title": "Python Basics: Your FIRST Program in Under a Minute! 🚀",
      "link": "https://www.youtube.com/shorts/nluUYtejoIE",
      "views_text": "1.7M views",
      "thumbnail": "https://i.ytimg.com/vi/nluUYtejoIE/oar2.jpg?sqp=-oaymwEoCJUDENAFSFqQAgHyq4qpAxcIARUAAIhC2AEB4gEKCBgQAhgGOAFAAQ==&rs=AOn4CLCuNV89Mvv4RG_YBfH0wDDrB1zpPg&usqp=CCk"
    }
  ],
  "channels": [
    {
      "position": 1,
      "channel_id": "UCKQdc0-Targ4nDIAUrlfKiA",
      "title": "Python Simplified",
      "handle": "@PythonSimplified",
      "link": "https://www.youtube.com/@PythonSimplified",
      "subscribers_text": "286K subscribers",
      "description": "Hi everyone! My name is Mariya and I'm a software developer recently moved to Sofia, Bulgaria. I film programming tutorials about ...",
      "verified": true,
      "thumbnail": "https://yt3.googleusercontent.com/ytc/AIdro_ngt_N86CG1gQ576UmAbpFyxnCZddjPWzzKXzTfxljsZkM=s176-c-k-c0x00ffffff-no-rj-mo"
    }
  ],
  "playlists": [
    {
      "position": 1,
      "playlist_id": "PLGjplNEQ1it8-0CmoljS5yeV-GlKSUEt0",
      "title": "Python Language Full Course (2026)",
      "link": "https://www.youtube.com/playlist?list=PLGjplNEQ1it8-0CmoljS5yeV-GlKSUEt0",
      "kind": "course",
      "label": "Course",
      "channel": {
        "name": "Shradha Khapra",
        "id": "UC1XBh-m27kkgwLAwu_SRJBg",
        "handle": "@shradhaKD",
        "link": "https://www.youtube.com/@shradhaKD",
        "verified": false
      },
      "video_count_text": "9 lessons",
      "first_video_id": "t2_Q2BRzeEE",
      "thumbnail": "https://i.ytimg.com/vi/t2_Q2BRzeEE/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLBm5_nQyrAnm5zyJ2FBA9l3BKyzMA"
    }
  ],
  "skipped_items": {},
  "next_page_token": "EroDEg9weXRob24gdHV0b3JpYWwapgNTQlNDQVF0cGVE…",
  "meta": {
    "source": "youtube",
    "wire_bytes": 1250151,
    "elapsed_s": 0.77
  }
}

Errors

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Status	Meaning	Retry?
`401`Unauthorized	Missing or invalid API key. `{"detail":"missing or invalid API key"}`	No, fix the request
`402`Payment Required	Not enough credits for this request. Only returned once credit enforcement is switched on; during the beta metering runs in shadow mode and never blocks. `{"detail":"insufficient credits: this request costs 5, 0 available. Credits renew 2026-11-01."}`	No, fix the request
`422`Unprocessable Content	Request validation failed. `detail` is a list of problems for schema errors, or a string for semantic checks performed by the endpoint. `{"detail":[{"loc":["body","name"],"msg":"Field required","type":"missing"}]}`	No, fix the request
`429`Too Many Requests	Too many requests: the key's requests-per-minute limit was exceeded, or (once credit enforcement is on) the plan's concurrent-request limit. No rate-limit or Retry-After headers are sent; back off and retry. `{"detail":"rate limit 60/min exceeded"}`	Yes, with backoff
`502`Bad Gateway	The upstream source failed, blocked the request or returned an unusable answer. Safe to retry later; failed requests are not charged. `{"detail":"RuntimeError"}`	Yes, with backoff
`503`Service Unavailable	Temporarily unavailable: a dependency of this endpoint is down, or the upstream source changed its contract. Retry later. `{"detail":"database unavailable: OperationalError"}`	Yes, with backoff

Try it

The quickest way: open this endpoint in Try it. It runs on your account with the example request filled in, shows the cost before you run, and shows the answer as a readable table next to the JSON and the code. Signed out? You sign in first and come straight back.

Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? request access).
Copy the cURL example above and run it in a terminal.
Or open the interactive playground on api.scrapercompany.com, paste your key and pick this endpoint.

Credits

2 credits per successful call (2 (an empty answer and failed requests are free)). Failed, blocked and empty results are free. Credit metering is in beta and does not block requests yet.

Request#

Body#

Example request#

Response#

Errors#

Try it#