POST /youtube_search • Credits: 1 credit per call

YouTube Search runs one keyword query against YouTube and returns up to 20 matching videos. The response holds a data.results array with the video ID, title, channel, view count, duration, thumbnail and a short description of each video. Each call costs 1 credit.

What does YouTube Search do?

YouTube Search answers the question "which videos exist for this keyword?" in one HTTP call. The endpoint sends the keyword text to YouTube and reads the public search result page. It returns the same 20 videos that a visitor sees at the top of the YouTube search results. Each result carries the video ID and the channel ID, which build the URLs that the other three YouTube endpoints accept as input. YouTube Search needs no Google account, no YouTube Data API key and no daily quota from Google.

Which endpoint does YouTube Search use?

Method: POST
URL: https://api.richapi.ai/api/v1/youtube_search
Authentication: x-api-key header
Response: Synchronous JSON
Credits: 1 credit per call
Results per call: Up to 20

How to send a YouTube Search request

Copy your API key from the RichAPI dashboard.
Set the query parameter to the keyword text.
To accept a cached result, set the cache parameter to true.
Send a POST request to https://api.richapi.ai/api/v1/youtube_search.
Send the API key in the x-api-key header.
Read the data.results array from the response.

CAUTION: Each YouTube Search call costs 1 credit. A query with no match also costs 1 credit.

cURL

curl -X POST https://api.richapi.ai/api/v1/youtube_search   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "query": "python tutorial",
    "cache": true
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/youtube_search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "query": "python tutorial",
        "cache": True,
    },
    timeout=60,
)
response.raise_for_status()
results = response.json()["data"]["results"]
for video in results:
    print(video["video_id"], video["view_count"], video["title"])

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/youtube_search", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "python tutorial",
    cache: true,
  }),
});

const data = await response.json();
console.log(data.data.results.map((video) => video.title));

Which parameters does YouTube Search accept?

Parameter	Type	Required	Default	Description
`query`	string	Yes	None	The keyword text to search for on YouTube. The text must hold 1 to 500 characters.
`cache`	boolean	No	`false`	Set to `true` to accept a cached result. Set to `false` to run a live search.

YouTube Search rejects any other field. An unknown field returns a 400 error that names the field and lists the supported fields.

Which search filters does YouTube Search accept?

YouTube Search accepts no filter parameter. The query string is the only control over the result set. The endpoint holds no parameter for the result count, the upload date, the video duration, the language or the channel. Every call returns the top 20 matches for the keyword text, in the order that YouTube ranks them.

To narrow a result set, put the qualifier inside the query text. A query such as "b2b saas onboarding walkthrough 2026" returns a different top 20 than "saas". To filter on view count, duration or upload date, read those fields from the response and filter in your own code.

What does YouTube Search return?

The block below is an example response for the query python tutorial. The field names and the structure are exact. The video IDs, the titles, the counts and the timings are illustrative. The example shows 3 of the 20 results.

{
  "data": {
    "results": [
      {
        "video_id": "rfscVS0vtbw",
        "title": "Learn Python - Full Course for Beginners",
        "channel": "freeCodeCamp.org",
        "channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
        "view_count": 48213905,
        "duration": 16214,
        "publish_date": "20180711",
        "thumbnail": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg",
        "description": "This course covers all of the core concepts of Python, from variables and loops to object-oriented programming."
      },
      {
        "video_id": "_uQrJ0TkZlc",
        "title": "Python Tutorial for Beginners - Full Course",
        "channel": "Programming with Mosh",
        "channel_id": "UCWv7vMbMWH4-V0ZXdmDpPBA",
        "view_count": 21470882,
        "duration": 21641,
        "publish_date": "20200218",
        "thumbnail": "https://i.ytimg.com/vi/_uQrJ0TkZlc/hqdefault.jpg",
        "description": "Python tutorial for beginners. Learn Python programming with a project-based approach."
      },
      {
        "video_id": "HGOBQPFzWKo",
        "title": "Python Full Course for Beginners in 12 Hours",
        "channel": "Corey Schafer",
        "channel_id": "UCCezIgC97PvUuR4_gbFUs5g",
        "view_count": 3904118,
        "duration": 43512,
        "publish_date": "20240305",
        "thumbnail": "https://i.ytimg.com/vi/HGOBQPFzWKo/hqdefault.jpg",
        "description": "A complete Python course that starts with the interpreter and ends with a deployed web application."
      }
    ]
  },
  "meta": {
    "cache_hit": false,
    "execution_time_ms": 3184,
    "quality_warning": null
  }
}

Which fields does the YouTube Search response hold?

Field	Type	Description
`data`	object	The result of the search.
`data.results`	array of objects	The matching videos, in the rank order of YouTube. The array holds up to 20 objects.
`data.results[].video_id`	string	The YouTube video ID. Add it to `https://www.youtube.com/watch?v=` and send that URL to the YouTube Video Details endpoint.
`data.results[].title`	string	The title of the video.
`data.results[].channel`	string	The display name of the channel that published the video.
`data.results[].channel_id`	string or null	The YouTube channel ID of the publisher.
`data.results[].view_count`	integer or null	The lifetime view count of the video. The value is `null` for a video that hides its count.
`data.results[].duration`	integer or null	The length of the video, in seconds.
`data.results[].publish_date`	string	The upload date of the video.
`data.results[].thumbnail`	string	The URL of the thumbnail image of the video.
`data.results[].description`	string	The description text of the video, cut to the first 500 characters. The value is an empty string for a video with no description.
`meta`	object	The metadata of the call.
`meta.cache_hit`	boolean	The value is `true` for a result served from the cache.
`meta.execution_time_ms`	integer	The duration of the call, in milliseconds.
`meta.quality_warning`	string or null	A note about a search that returned no data. The value is `null` for a normal search.

How do you get the full detail of a video that YouTube Search found?

YouTube Search returns a summary of each video. It returns no like count, no comment count, no tag list, no chapter list and no captions. The natural pairing is a search call, then one YouTube Video Details call per video that matters.

Send a YouTube Search request with your keyword as query.
Read the video_id value of each result.
Filter the 20 results in your own code on view_count or publish_date.
Build the watch URL from each remaining video_id, then send a YouTube Video Details request for each URL.
Store the full record against the video.

One search call plus 20 detail calls costs 21 credits, or $0.42. A filter step in step 3 cuts that cost. One search call plus the 5 best results costs 6 credits, or $0.12.

How do you find creators for a partnership with YouTube Search?

A partnership search starts with a topic and ends with a shortlist of channels. YouTube Search turns the topic into 20 videos and names the channel behind each one.

Send a YouTube Search request for the topic of your product.
Collect the channel and channel_id values from data.results.
Remove the duplicate channels from the list.
Send a YouTube Channel Info request for each remaining channel.
Rank the channels on subscriber count and on the external links in the profile.
Contact the channels at the top of the ranked list.

Run steps 1 and 2 for several related keywords. A channel that appears in the top 20 for three keywords covers the topic in depth.

How do you monitor the YouTube content of a competitor?

A competitor monitor is a repeat search on a fixed keyword set. The view_count and publish_date fields make the change between two runs visible.

Write down the keyword set that matters to your market.
Send one YouTube Search request per keyword, with cache set to false.
Store each result row against the run date, keyed on video_id.
Compare the new run against the last run.
Report a video_id that is new to the top 20 as a new competitor video.
Report a large rise in view_count as a video that gains traction.

A daily monitor over 20 keywords costs 20 credits per day, or $0.40. That is 600 credits per month, or $12.00.

CAUTION: For a monitor, set cache to false. A cached response repeats the result of the last 6 hours and hides a change.

Which YouTube endpoint do you need?

RichAPI holds four YouTube endpoints. YouTube Search is the entry point, because the other three need a video URL or a channel URL as input.

Endpoint	Path	What it returns	Credits
YouTube Search	`/youtube_search`	Up to 20 videos for a keyword query, with IDs, titles, channels, view counts and thumbnails.	1
YouTube Video Details	`/youtube_video`	The full record of one video: description, view and like counts, duration, tags, thumbnails and chapters.	1
YouTube Channel Info	`/youtube_channel`	The profile of one channel: name, subscriber count, description, avatar, banner and external links.	1
YouTube Channel Videos	`/youtube_channel_videos`	Up to 50 of the most recent videos of one channel, with titles, view counts and durations.	2

How much does YouTube Search cost?

YouTube Search costs 1 credit per call. 1 credit costs $0.02 on the 1,000 and 5,000 credit packs, and less on larger packs. The table uses $0.02. The credit count does not change with the number of results. A call that returns 20 videos and a call that returns none both cost 1 credit.

Calls	Credits	Cost
1	1	$0.02
100	100	$2.00
1,000	1,000	$20.00
10,000	10,000	$200.00

A search call plus one YouTube Video Details call per result costs 21 credits, or $0.42 per keyword.

Which errors can YouTube Search return?

Status	Meaning	What to do
`400`	The request body failed validation.	Correct the parameter that the message names. Send only `query` and `cache`.
`422`	The `query` value is empty or longer than 500 characters.	Send a `query` string of 1 to 500 characters.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`403`	This API key has no access to this endpoint (`Endpoint not available on your plan`).	Call `GET /api/v1/my-endpoints` to see the endpoints that this key can use. Contact support for access.
`404`	The endpoint name is wrong.	Send the request to `/youtube_search`.
`429`	The request rate is over the limit.	Wait, then send the request again. For a higher limit, contact support.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.
`502`	YouTube did not answer.	Wait a few seconds, then send the request again.

RichAPI charges no credit for a 400, 401, 403, 404, 422, 429, 500 or 502 response.

Frequently asked questions

How many results does one YouTube Search call return?

One YouTube Search call returns up to 20 videos in the data.results array. The count is fixed, and no parameter changes it. A narrow query can return fewer than 20 videos.

Can you ask YouTube Search for more than 20 results?

No. YouTube Search accepts two parameters, query and cache. A request that holds a max_results field returns a 400 error, because YouTube Search treats an unknown field as a validation failure.

Does YouTube Search need a YouTube Data API key?

No. YouTube Search needs only your RichAPI key in the x-api-key header. It consumes no Google quota, so a high call volume never blocks a Google project of yours.

How long does YouTube Search cache a result?

YouTube Search caches a search for 6 hours. To accept a cached result inside that window, set cache to true. The meta.cache_hit field reports the source. A cached call and a live call both cost 1 credit.

What does YouTube Search return for a query with no match?

The data.results array is empty, and meta.quality_warning holds the text Search returned no results. The call still costs 1 credit, because the search ran.

How do you get the like count or the tags of a search result?

YouTube Search returns no like count and no tag list. Add the video_id of the result to https://www.youtube.com/watch?v=, then send that URL to the YouTube Video Details endpoint for 1 more credit.

What is the difference between YouTube Search and YouTube Channel Videos?

YouTube Search takes a keyword and returns up to 20 videos from any channel for 1 credit. YouTube Channel Videos takes one channel URL and returns up to 50 of the most recent videos of that channel for 2 credits.

YouTube Search API