google-videos-api

Google Videos API

The Google Videos tab as JSON. Every result comes back with the platform it lives on, the channel that posted it, how long it runs and when it went up, so you can rank and filter video without watching any.

Endpoint

One credit per request. A page carries ten videos, the same ten Google ranks.

GET/v1/videos

bash

curl "https://api.serpix.io/v1/videos?q=how+to+tie+a+tie&hl=en" \
  -H "Authorization: Bearer $SERPIX_API_KEY"

The same parameters are accepted as a JSON body on POST /v1/videos:

post variant

curl -X POST "https://api.serpix.io/v1/videos" \
  -H "Authorization: Bearer $SERPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "how to tie a tie", "hl": "en"}'

Parameters

Query and localization
field	type	default	description
qrequired	string	–	The search query.
gl	string	–	Country to search from, two-letter code. Defaults to `us`.
hl	string	en	Language of the results page, two-letter code.

Results

Results
field	type	default	description
device	desktop \| mobile \| tablet	desktop	Results as Google serves them to a desktop browser or a phone.
page	integer	1	1-based page. Each page is a fresh ten videos. One credit per page.
autocorrect	boolean	true	Set `false` to search the query exactly as typed, excluding results Google returns for its spell-corrected guess.
safe	active \| off	off	SafeSearch. `active` filters explicit results.

Video filters

Video filters
field	type	default	description
duration	short \| medium \| long	–	Length bucket: `short` under 4 minutes, `medium` 4 to 20, `long` over 20.
uploaded	hour \| day \| week \| month \| year	–	Only videos published within this window.

Rejected parameters

Unknown parameters are never silently ignored. A request carrying one is rejected with 422 before any search runs, so a typo can't bill you for results you didn't ask for. Common parameters from raw Google URLs and other SERP APIs get a pointed message naming the equivalent here:

Rejected aliases
field	type	default	description
num	422	–	Google serves a fixed page of ten videos. Paginate with `page`.
start	422	–	Use `page`, a 1-based page number, instead of a result offset.
tbs	422	–	Use the named filters: `duration` and `uploaded`.
quality / hd	422	–	Google ignores the HD filter on this vertical: the same results come back, reshuffled.
nfpr	422	–	Use `autocorrect`.
location / uule	422	–	Use `gl` and `hl`. City-level geotargeting is not wired for this vertical.
lr	422	–	Not supported on this vertical.
udm / tbm	422	–	Not needed. This endpoint is the videos vertical.
engine	422	–	Not needed. This endpoint is Google Videos.
api_key	422	–	Authenticate with the `Authorization` header, never the query string.

422 · rejected parameter

HTTP/2 422
content-type: application/json

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query"],
      "msg": "Value error, `tbs` is not supported: use the semantic filters: `duration`, `uploaded`",
      "input": { "q": "python tutorial", "tbs": "dur:l", ... }
    }
  ]
}

Response

A search returns one JSON object: two envelope objects that are always present (search_metadata, search_parameters), the ranking as video_results, and whatever else Google served around it. A field that wasn't served is omitted entirely, never null, never [], so a presence check is all you need before reading one.

200 · trimmed

{
  "search_metadata": {
    "id": "srx_Urg7EKdeNodKk6qz",
    "status": "success",
    "created_at": "2026-07-28T18:00:16Z",
    "took_ms": 1159,
    "parser_version": "2026.07.1",
    "google_url": "https://www.google.com/search?q=how+to+tie+a+tie&udm=7&hl=en&gl=us&...",
    "html_url": "https://api.serpix.io/searches/srx_Urg7EKdeNodKk6qz/eH4EKukfiUrl3BSC.html",
    "json_url": "https://api.serpix.io/searches/srx_Urg7EKdeNodKk6qz/eH4EKukfiUrl3BSC.json"
  },
  "search_parameters": {
    "q": "how to tie a tie",
    "gl": "us",
    "hl": "en",
    "device": "desktop",
    "page": 1
  },
  "video_results": [
    {
      "position": 1,
      "title": "How to Tie a Tie",
      "link": "https://www.youtube.com/shorts/ufEzBcn8yQY",
      "displayed_link": "www.youtube.com › shorts",
      "snippet": "Share your videos with friends, family, and the world.",
      "platform": "YouTube",
      "channel": "Parker York Smith",
      "duration": "1:23",
      "date": "Oct 19, 2025",
      "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSzQz2jQPF8OKfPFV...",
      "about_page_link": "https://www.google.com/search/about-this-result?origin=www.google.com&req=Cipod..."
    },
    ...
  ],
  "people_also_search_for": [
    {
      "query": "how to tie a tie in 3 steps",
      "link": "https://www.google.com/search?udm=7&hl=en&gl=us&q=How+to+tie+a+tie+in+3+steps&..."
    },
    ...
  ],
  "pagination": {
    "current": 1,
    "next": "https://www.google.com/search?q=how+to+tie+a+tie&udm=7&hl=en&gl=us&start=10&..."
  }
}

Every response also reports its cost in the X-Serpix-Credits-Charged and X-Serpix-Credits-Remaining headers.

The ranking

Each result becomes one entry of video_results. The capture below is the page exactly as Google served it, beside the JSON it parsed into:

The rankingHover or tap a tile to pair it with its entry

video_results

[  {
    "position": 1,
    "title": "How to Tie a Tie",
    "link": "https://www.youtube.com/shorts/ufEzBcn8yQY",
    "displayed_link": "www.youtube.com › shorts",
    "snippet": "Share your videos with friends, family, and the world.",
    "platform": "YouTube",
    "channel": "Parker York Smith",
    "duration": "1:23",
    "date": "Oct 19, 2025",
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRrQL00tV-G7V...",
    "about_page_link": "https://www.google.com/search/about-this-result?origin=www.goo..."
  },  {
    "position": 2,
    "title": "How To Tie The Easiest Tie Knot (The \"Oriental\" Knot)",
    "link": "https://www.youtube.com/shorts/Gi6m55ZGa1M?vl=en-US",
    "displayed_link": "www.youtube.com › shorts",
    "snippet": "Hands down the easiest tie knot - perfect for a stylish, elegant look that anyone can do!...",
    "platform": "YouTube",
    "channel": "Gentleman's Gazette",
    "duration": "1:02",
    "date": "Apr 29, 2026",
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR4mbDvjbAfBM...",
    "about_page_link": "https://www.google.com/search/about-this-result?origin=www.goo..."
  },  {
    "position": 3,
    "title": "How to Tie a Tie Easily",
    "link": "https://www.youtube.com/watch?v=TATblk1LUQI",
    "displayed_link": "www.youtube.com › watch",
    "snippet": "Learn how to tie a tie properly with this quick step-by-step guide—get the perfect knot...",
    "platform": "YouTube",
    "channel": "Dad, how do I?",
    "duration": "2:02",
    "date": "Apr 2, 2020",
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRb78Hzybbg0H...",
    "about_page_link": "https://www.google.com/search/about-this-result?origin=www.goo...",
    "key_moments": "[3 chapters]"
  },  {
    "position": 4,
    "title": "How to tie a tie #menswear #howto #howtotieatie",
    "link": "https://www.youtube.com/shorts/mbV-6qwTf8U",
    "displayed_link": "www.youtube.com › shorts",
    "snippet": "Share your videos with friends, family, and the world.",
    "platform": "YouTube",
    "channel": "Rhodes Wood",
    "duration": "1:01",
    "date": "May 29, 2025",
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSiB-oqgkTx-M...",
    "about_page_link": "https://www.google.com/search/about-this-result?origin=www.goo..."
  },  {
    "position": 5,
    "title": "How to Tie a Tie (Mirrored / Slowly) - Full Windsor Knot",
    "link": "https://www.youtube.com/watch?v=xAg7z6u4NE8",
    "displayed_link": "www.youtube.com › watch",
    "snippet": "How to tie a tie step by step tutorial. If you want quick and easy you can use the gear...",
    "platform": "YouTube",
    "channel": "tiehole",
    "duration": "5:41",
    "date": "Jul 28, 2010",
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRJ56ATzD78k-...",
    "about_page_link": "https://www.google.com/search/about-this-result?origin=www.goo...",
    "key_moments": "[9 chapters]"
  }]

Google prints the duration, the description and the “platform · channel · date” line as one run of text. Serpix splits them back apart, so snippet is the description alone and the attribution arrives as its own fields.

search_metadata

search_metadata fields
field	type	default	description
id	string	–	Unique id of this search, `srx_` prefixed.
status	string	–	`success` on every 200.
created_at	string	–	When the search ran, ISO 8601 UTC.
took_ms	integer	–	End-to-end time to serve this response, in milliseconds.
parser_version	string	–	Dated version of the videos parser that produced this response, so any response can be tied to the parsing behaviour that made it. Each vertical carries its own.
google_url	string	–	The exact Google URL fetched.
html_url	string	–	Archived copy of the results page exactly as served. Included when available.
json_url	string	–	Archived copy of this JSON response. Included when available.

search_parameters

The parameters the search actually ran with, defaults filled in. A filter appears only when you sent it.

search_parameters fields
field	type	default	description
q	string	–	The query as received.
gl	string	–	Country the search ran from, defaulting to `us`.
hl	string	–	Language used.
device	string	–	Device profile used.
page	integer	–	Page served.
duration	string	–	Length bucket applied. Present when sent.
uploaded	string	–	Recency window applied. Present when sent.

video_results

video_results entry fields
field	type	default	description
position	integer	–	Rank on the page, starting at 1.
title	string	–	Title of the video, as Google shows it.
link	string	–	The video on the platform hosting it: a YouTube watch or shorts URL, a TikTok video, an Instagram reel, a Facebook video.
displayed_link	string	–	The URL breadcrumb printed above the title.
snippet	string	–	The description, with the duration and the attribution line stripped back off. Absent when Google prints none.
platform	string	–	Where the video lives: `YouTube`, `TikTok`, `Instagram`, `Facebook`, `Reddit`. On a video hosted by the publisher itself, this is that publisher.
channel	string	–	The account that posted it.
duration	string	–	Running time as displayed, `m:ss` or `h:mm:ss`.
date	string	–	Upload date as displayed: an exact date on older videos, an age like `2 days ago` on recent ones.
thumbnail	string	–	Preview frame, served from Google's cache.
key_moments	list	–	The video's chapters, when Google shows them. Present on about half the results of a typical page.
about_page_link	string	–	Google's “about this result” panel for this video.

key_moments

A result carrying key_moments lists every chapter Google reads off the video, each with a link that opens the video at that instant:

json

{
  "position": 1,
  "title": "Intro",
  "timestamp": "00:00",
  "seconds": 0,
  "link": "https://www.youtube.com/watch?v=TATblk1LUQI&t=0",
  "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRb78..."
}

key_moments entry fields
field	type	default	description
position	integer	–	Order within the video, starting at 1.
title	string	–	What the chapter is called.
timestamp	string	–	Where it starts, as displayed.
seconds	integer	–	The same instant in seconds, ready to compute with.
link	string	–	The video, opened at this chapter.
thumbnail	string	–	Frame from this moment.

channel_results

Google ranks channel pages between the videos, and searching a creator's name usually puts their channel first. Those carry no duration and no upload date, so they come back as channel_results rather than as videos with empty fields. Both lists share one set of positions, so a video at 2 really is the second thing on the page.

channel_results entry fields
field	type	default	description
position	integer	–	Rank on the page, counted with the videos.
title	string	–	Name of the channel.
link	string	–	The channel page.
displayed_link	string	–	The URL breadcrumb printed above the title.
snippet	string	–	Channel description as Google shows it, subscriber count and all.
thumbnail	string	–	Channel image, when one is served.

The queries Google lists under the results, each with the videos search it runs. Filtered pages carry none, which is Google's own behaviour rather than a gap.

people_also_search_for entry fields
field	type	default	description
query	string	–	The related query, as displayed.
link	string	–	Google Videos search for that query.

pagination

Ask for the next page with page. next is there whenever another page exists, so its absence is how you know you have reached the end.

pagination fields
field	type	default	description
current	integer	–	The page this response is.
next	string	–	Google URL for the next page. Absent on the last one.

Errors

A rejected request answers with detail, naming the parameter and what to send in its place. A search that could not be completed answers with error and a search_id you can quote. No error is ever charged.

Status codes
field	type	default	description
401	unauthorized	−0	Missing, malformed, or revoked key. See Authentication.
402	payment required	−0	The balance can't cover a search. See Credits & billing.
422	invalid request	−0	Unknown or invalid parameter. The `detail` names the parameter and what to send in its place.
502	search_failed	−0	The search could not be completed. Retry it; you were not charged.
503	search_unavailable	−0	Google did not serve a usable results page. Retry it; you were not charged.

502 · search failed

HTTP/2 502
content-type: application/json
x-serpix-credits-charged: 0

{ "error": { "code": "search_failed", "search_id": "srx_kq3v9tR2xLw8mA1c" } }