POST /youtube_video • Credits: 1 credit per call

YouTube Video Details takes one YouTube video URL and returns the full record of that video. The response holds a data object with the title, the full description, the channel, the view count and the like count. The same object holds the duration in seconds, the tags, the categories, the thumbnails and the chapters. Each call costs 1 credit.

What does YouTube Video Details do?

A YouTube search result gives you a video ID and a title. It does not give you the numbers that tell you whether the video matters. YouTube Video Details fills that gap for one video at a time. The endpoint reads the public video page and returns the complete metadata record, with the engagement counts and the full description text. RichAPI extracts the data directly from YouTube, so you need no YouTube Data API key and no OAuth token. One call covers one video.

Which endpoint does YouTube Video Details use?

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

How to send a YouTube Video Details request

Copy your API key from the RichAPI dashboard.
Set the url parameter to the full YouTube video URL.
To get the English captions, set include_captions to true.
To accept a cached result, set cache to true.
Send a POST request to https://api.richapi.ai/api/v1/youtube_video.
Send the API key in the x-api-key header.
Read the video fields from the data object of the response.

CAUTION: Each YouTube Video Details call costs 1 credit. A cached result costs the same 1 credit.

cURL

curl -X POST https://api.richapi.ai/api/v1/youtube_video   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "url": "https://www.youtube.com/watch?v=V8cLbbtaLcE",
    "include_captions": false,
    "cache": true
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/youtube_video",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "url": "https://www.youtube.com/watch?v=V8cLbbtaLcE",
        "include_captions": False,
        "cache": True,
    },
    timeout=60,
)
response.raise_for_status()
video = response.json()["data"]
print(video["title"], video["view_count"], video["like_count"])

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/youtube_video", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.youtube.com/watch?v=V8cLbbtaLcE",
    include_captions: false,
    cache: true,
  }),
});

const { data } = await response.json();
console.log(data.title, data.view_count, data.like_count);

Which parameters does YouTube Video Details accept?

Parameter	Type	Required	Default	Description
`url`	string	Yes	None	The full YouTube video URL. The maximum length is 2048 characters.
`include_captions`	boolean	No	`false`	Set to `true` to add the English caption text to the response.
`cache`	boolean	No	`false`	Set to `true` to accept a cached result. Set to `false` to read the live video page.

YouTube Video Details accepts these three parameters and no other. If the request body holds any other field, the API returns a 400 error that names the unknown field.

Which video URL formats does YouTube Video Details accept?

YouTube Video Details accepts a full video URL. The endpoint validates the url parameter against three URL forms.

Form	Example	Accepted
Watch page	`https://www.youtube.com/watch?v=V8cLbbtaLcE`	Yes
Short link	`https://youtu.be/V8cLbbtaLcE`	Yes
Shorts page	`https://www.youtube.com/shorts/V8cLbbtaLcE`	Yes
Mobile host	`https://m.youtube.com/watch?v=V8cLbbtaLcE`	Yes
Bare video ID	`V8cLbbtaLcE`	No
Channel or playlist URL	`https://www.youtube.com/@SaaSAcademy`	No

CAUTION: Do not send a bare video ID. The API rejects the request with a 422 error and charges no credit.

If you hold only a video ID, build the watch URL first. Add the ID to the end of https://www.youtube.com/watch?v=. The result is a valid input for YouTube Video Details.

What does YouTube Video Details return?

The block below is an example response for one video, with include_captions set to false. The field names, the types and the structure are exact. The title, the counts and the URLs are illustrative.

{
  "data": {
    "video_id": "V8cLbbtaLcE",
    "title": "How to Build a SaaS Onboarding Flow",
    "description": "In this video we walk through the full onboarding flow of a B2B SaaS product, from the signup form to the first activation moment.",
    "channel": "SaaS Academy",
    "channel_id": "UC9x0AN7BWHPCDcrSxAjRQyw",
    "view_count": 45217,
    "like_count": 1236,
    "duration": 754,
    "upload_date": "20260215",
    "tags": ["saas", "onboarding", "product demo", "user activation"],
    "categories": ["Education"],
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/V8cLbbtaLcE/hqdefault.jpg",
        "width": 480,
        "height": 360
      },
      {
        "url": "https://i.ytimg.com/vi/V8cLbbtaLcE/maxresdefault.jpg",
        "width": 1280,
        "height": 720
      }
    ],
    "chapters": [
      { "title": "Intro", "start_time": 0.0, "end_time": 42.0 },
      { "title": "The signup form", "start_time": 42.0, "end_time": 310.0 },
      { "title": "First activation", "start_time": 310.0, "end_time": 754.0 }
    ],
    "captions": null
  },
  "meta": {
    "cache_hit": false,
    "execution_time_ms": 3184,
    "quality_warning": null
  }
}

The duration value is a whole number of seconds. The value 754 means 12 minutes and 34 seconds. The upload_date value uses the YYYYMMDD form, so 20260215 means 15 February 2026.

Which fields does the YouTube Video Details response hold?

Field	Type	Description
`data`	object	The full record of the video.
`data.video_id`	string	The YouTube ID of the video, such as `V8cLbbtaLcE`.
`data.title`	string	The title of the video.
`data.description`	string	The full description text under the video. The API returns the whole text.
`data.channel`	string	The display name of the channel.
`data.channel_id`	string	The YouTube channel ID, such as `UC9x0AN7BWHPCDcrSxAjRQyw`.
`data.view_count`	integer or null	The number of views. The value is `null` for a video that hides the count.
`data.like_count`	integer or null	The number of likes. The value is `null` for a video that hides the count.
`data.duration`	integer or null	The length of the video, in seconds.
`data.upload_date`	string	The publication date in the `YYYYMMDD` form, such as `20260215`.
`data.tags`	array of strings	The tags of the video. The array is empty for a video with no tags.
`data.categories`	array of strings	The YouTube categories of the video, such as `Education`.
`data.thumbnails`	array of objects	Every thumbnail image of the video, from the smallest to the largest.
`data.thumbnails[].url`	string	The direct image URL of the thumbnail.
`data.thumbnails[].width`	integer or null	The width of the thumbnail, in pixels.
`data.thumbnails[].height`	integer or null	The height of the thumbnail, in pixels.
`data.chapters`	array of objects	The chapters of the video. The array is empty for a video with no chapters.
`data.chapters[].title`	string	The title of the chapter.
`data.chapters[].start_time`	number or null	The start of the chapter, in seconds from the beginning of the video.
`data.chapters[].end_time`	number or null	The end of the chapter, in seconds from the beginning of the video.
`data.captions`	string or null	The English caption text. The value is `null` when `include_captions` is `false`.
`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 call that returned no data. The value is `null` for a normal call.

Does YouTube Video Details return the description and the transcript?

YouTube Video Details always returns the full description in data.description. The endpoint does not truncate that text. The description holds the links, the timestamps and the contact details that the creator writes under the video.

The transcript is a separate parameter. Set include_captions to true to add the English caption text to data.captions. The endpoint reads the manual English captions first, and falls back to the auto-generated English captions. If the video carries no English captions, data.captions holds null.

curl -X POST https://api.richapi.ai/api/v1/youtube_video   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "url": "https://www.youtube.com/watch?v=V8cLbbtaLcE",
    "include_captions": true
  }'

The include_captions parameter costs no extra credit. It does add time to the call, because the endpoint reads the caption track as well as the video page.

Which engagement metrics does YouTube Video Details return?

YouTube Video Details returns three engagement signals for one video.

Metric	Field	Type
Views	`data.view_count`	integer or null
Likes	`data.like_count`	integer or null
Length	`data.duration`	integer or null

A creator can hide the like count on a video. For such a video, data.like_count holds null and the call still costs 1 credit. Read the like rate from the two counts. For the example above, 1,236 likes against 45,217 views is a like rate of 2.7 percent.

YouTube Video Details returns no comment count and no subscriber count. For the subscriber count of the channel, send the URL https://www.youtube.com/channel/ followed by data.channel_id to the YouTube Channel Info endpoint.

How do you search YouTube and then fetch video details?

YouTube Search and YouTube Video Details work as a pair. YouTube Search takes a keyword query and returns up to 20 shallow results. YouTube Video Details takes one of those results and returns the full record. Run the two in sequence, and fetch the detail only for the videos that pass your filter.

Send a YouTube Search request with your keyword as query.
Read the data.results array from the search response.
Filter the results on the title, the channel and the view count.
For each video that passes the filter, build the watch URL from video_id.
Send a YouTube Video Details request for each of those URLs.
Store the description, the tags, the chapters and the like count.

import requests

HEADERS = {"x-api-key": "YOUR_API_KEY"}
BASE_URL = "https://api.richapi.ai/api/v1"

search = requests.post(
    f"{BASE_URL}/youtube_search",
    headers=HEADERS,
    json={"query": "saas onboarding flow", "cache": True},
    timeout=60,
)
search.raise_for_status()
results = search.json()["data"]["results"]

# Keep the five most viewed results, then fetch the full record for each one.
top = sorted(results, key=lambda r: r.get("view_count") or 0, reverse=True)[:5]

for result in top:
    detail = requests.post(
        f"{BASE_URL}/youtube_video",
        headers=HEADERS,
        json={
            "url": f"https://www.youtube.com/watch?v={result['video_id']}",
            "cache": True,
        },
        timeout=60,
    )
    detail.raise_for_status()
    video = detail.json()["data"]
    print(video["title"], video["like_count"], video["tags"])

The two-step flow costs 1 credit for the search and 1 credit for each detail call.

Step	Calls	Credits	Cost
Search	1	1	$0.02
Detail on 5 results	5	5	$0.10
Total per query	6	6	$0.12

If you fetch the detail for all 20 search results, one query costs 21 credits, or $0.42. For 50 queries at 5 details each, the total is 300 credits, or $6.00.

CAUTION: Do not fetch the detail for every search result by default. The filter step in the middle is what keeps the cost down.

How much does YouTube Video Details cost?

YouTube Video Details 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 length of the video, the number of tags or the value of include_captions.

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

RichAPI charges the credit on a 200 response. A 200 response with a meta.quality_warning value also costs 1 credit.

Which errors can YouTube Video Details return?

Status	Meaning	What to do
`400`	The request body failed validation.	Correct the parameter that the message names. Remove any field outside `url`, `include_captions` and `cache`.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	The organization has no credits left, or the team reached its monthly spend limit.	Buy credits in the RichAPI dashboard.
`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_video`.
`422`	The `url` value is not a YouTube video URL.	Send a full `youtube.com/watch`, `youtu.be` or `youtube.com/shorts` URL.
`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`	The upstream service did not answer.	Wait a few seconds, then send the request again.

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

Frequently asked questions

Does YouTube Video Details accept a video ID?

No. YouTube Video Details accepts a full YouTube video URL and rejects a bare video ID with a 422 error. If you hold only the ID, add it to the end of https://www.youtube.com/watch?v= and send that URL.

Does YouTube Video Details return the transcript of a video?

Yes, for a video with English captions. Set include_captions to true, and the endpoint returns the English caption text in data.captions. For a video with no English captions, data.captions holds null.

Does YouTube Video Details return the full description?

Yes. The data.description field holds the complete description text of the video, with no truncation. The description often holds the website link and the contact details of the creator.

Do I need a YouTube Data API key to use YouTube Video Details?

No. RichAPI reads the public video page directly, so one RichAPI key covers every YouTube endpoint. You need no YouTube Data API key, no Google Cloud project and no OAuth consent screen.

Why is like_count null for some videos?

A creator can hide the like count on a video. For such a video, YouTube publishes no like number, and data.like_count holds null. The call still returns the title, the description and the view count, and it still costs 1 credit.

What unit does the duration field use?

The duration field holds a whole number of seconds. A value of 754 means a video of 12 minutes and 34 seconds. The field is not an ISO 8601 duration string.

Does YouTube Video Details work on a Shorts URL?

Yes. YouTube Video Details accepts a youtube.com/shorts/ URL and returns the same fields as for a watch URL. A Short is a normal video with a short duration.

How long does YouTube Video Details cache a result?

YouTube Video Details caches a video record 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.

YouTube Video Details API