Videos Search
Requires API Key: Get one at https://api.search.brave.com
Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe
Quick Start (cURL)
Basic Search
curl -s "https://api.search.brave.com/res/v1/videos/search?q=python+tutorial" \
-H "Accept: application/json" \
-H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"
With Parameters
curl -s "https://api.search.brave.com/res/v1/videos/search" \
-H "Accept: application/json" \
-H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
-G \
--data-urlencode "q=machine learning explained" \
--data-urlencode "country=US" \
--data-urlencode "search_lang=en" \
--data-urlencode "count=20" \
--data-urlencode "freshness=pm"
Endpoint
GET https://api.search.brave.com/res/v1/videos/search
POST https://api.search.brave.com/res/v1/videos/search
Authentication: X-Subscription-Token: <API_KEY> header
Note: Both GET and POST methods are supported. POST is useful for long queries.
Parameters
| Parameter |
Type |
Required |
Default |
Description |
q |
string |
Yes |
- |
Search query (1-400 chars, max 50 words) |
country |
string |
No |
US |
Search country (2-letter country code or ALL) |
search_lang |
string |
No |
en |
Language preference (2+ char language code) |
ui_lang |
string |
No |
en-US |
UI language (e.g., "en-US") |
count |
int |
No |
20 |
Number of results (1-50) |
offset |
int |
No |
0 |
Page offset (0-9) |
safesearch |
string |
No |
moderate |
Adult content filter (off/moderate/strict) |
freshness |
string |
No |
- |
Time filter (pd/pw/pm/py or date range) |
spellcheck |
bool |
No |
true |
Auto-correct query |
operators |
bool |
No |
true |
Apply search operators |
include_fetch_metadata |
bool |
No |
false |
Include fetched_content_timestamp in results |
Freshness Values
| Value |
Description |
pd |
Past day (24 hours) |
pw |
Past week (7 days) |
pm |
Past month (31 days) |
py |
Past year (365 days) |
YYYY-MM-DDtoYYYY-MM-DD |
Custom date range |
Response Format
{
"type": "videos",
"query": {
"original": "python tutorial",
"spellcheck_off": false
},
"extra": {
"might_be_offensive": false
},
"results": [
{
"type": "video_result",
"title": "Python Tutorial for Beginners",
"url": "https://www.youtube.com/watch?v=rfscVS0vtbw",
"description": "Learn Python programming from scratch...",
"age": "February 12, 2025",
"page_age": "2025-02-12T00:00:00",
"page_fetched": "2025-02-12T15:00:00Z",
"thumbnail": {
"src": "https://imgs.search.brave.com/...",
"original": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg"
},
"video": {
"duration": "03:45:00",
"views": 1523000,
"creator": "freeCodeCamp",
"publisher": "YouTube",
"requires_subscription": false,
"tags": ["python", "programming"],
"author": {
"name": "freeCodeCamp.org",
"url": "https://www.youtube.com/@freecodecamp"
}
},
"meta_url": {
"scheme": "https",
"netloc": "youtube.com",
"hostname": "www.youtube.com",
"favicon": "https://imgs.search.brave.com/...",
"path": "\u203a watch"
}
}
]
}
Response Fields
| Field |
Type |
Description |
type |
string |
Always "videos" |
query.original |
string |
The original search query |
query.altered |
string? |
Spellcheck-corrected query (if changed) |
query.cleaned |
string? |
Cleaned/normalized query |
query.spellcheck_off |
bool? |
Whether spellcheck was disabled |
query.show_strict_warning |
bool? |
True if strict safesearch blocked adult results |
query.search_operators |
object? |
Applied search operators (applied, cleaned_query, sites) |
extra.might_be_offensive |
bool |
Whether results may contain offensive content |
results[].type |
string |
Always "video_result" |
results[].url |
string |
Source URL of the video |
results[].title |
string |
Video title |
results[].description |
string? |
Video description |
results[].age |
string? |
Human-readable age (e.g. "6 months ago") or absolute date (e.g. "February 12, 2025") |
results[].page_age |
string? |
Page age from source (ISO datetime) |
results[].page_fetched |
string? |
ISO datetime when page was last fetched (e.g. 2025-02-12T15:00:00Z) |
results[].fetched_content_timestamp |
int? |
Fetch timestamp (only with include_fetch_metadata=true) |
results[].video.duration |
string? |
Time string (variable format) |
results[].video.views |
int? |
View count as integer |
results[].video.creator |
string? |
Channel/creator name |
results[].video.publisher |
string? |
Platform (YouTube, Vimeo, etc.) |
results[].video.requires_subscription |
bool? |
Whether video requires a subscription |
results[].video.tags |
list[str]? |
Tags relevant to the video |
results[].video.author |
object? |
Author profile |
results[].video.author.name |
string |
Author name |
results[].video.author.url |
string |
Author profile URL |
results[].video.author.long_name |
string? |
Extended author name |
results[].video.author.img |
string? |
Author profile image URL |
results[].thumbnail.src |
string |
Served thumbnail URL |
results[].thumbnail.original |
string? |
Original thumbnail URL |
results[].meta_url.scheme |
string? |
URL protocol scheme |
results[].meta_url.netloc |
string? |
Network location |
results[].meta_url.hostname |
string? |
Lowercased domain name |
results[].meta_url.favicon |
string? |
Favicon URL |
results[].meta_url.path |
string? |
URL path |
Search Operators
Use search operators to refine results:
site:youtube.com - Limit to specific site"exact phrase" - Match exact phrase-exclude - Exclude term
Set operators=false to disable operator parsing.
Use Cases
- Video content research: Find tutorials, explainers, and reviews by topic. Use the
video.duration, video.views, and video.creator metadata to filter and rank results programmatically. Prefer videos-search over web-search when you need a dedicated video index with richer metadata (duration, views, creator, tags) and up to 50 results per request.
- Fresh video monitoring: Use
freshness=pd or freshness=pw to track newly published video content on trending topics or specific subjects.
- Platform-specific search: Use
site:youtube.com or site:vimeo.com operators to target specific video platforms.
- Video metadata extraction: Get view counts, durations, creator info, and tags for analytics, content curation, or recommendation systems.
Notes
- Pagination: Use
offset (0-9) with count for more results
- Max results: Up to 50 results per request
1---2name: videos-search3description: USE FOR video search. Returns videos with title, URL, thumbnail, duration, view count, creator. Supports freshness filters, SafeSearch, pagination.4---5
6# Videos Search
7
8> **Requires API Key**: Get one at https://api.search.brave.com
9>
10> **Plan**: Included in the **Search** plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe
11
12## Quick Start (cURL)
13
14### Basic Search
15```bash
16curl -s "https://api.search.brave.com/res/v1/videos/search?q=python+tutorial" \
17 -H "Accept: application/json" \
18 -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"
19```
20
21### With Parameters
22```bash
23curl -s "https://api.search.brave.com/res/v1/videos/search" \
24 -H "Accept: application/json" \
25 -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
26 -G \
27 --data-urlencode "q=machine learning explained" \
28 --data-urlencode "country=US" \
29 --data-urlencode "search_lang=en" \
30 --data-urlencode "count=20" \
31 --data-urlencode "freshness=pm"
32```
33
34## Endpoint
35
36```http
37GET https://api.search.brave.com/res/v1/videos/search
38POST https://api.search.brave.com/res/v1/videos/search
39```
40
41**Authentication**: `X-Subscription-Token: <API_KEY>` header
42
43**Note**: Both GET and POST methods are supported. POST is useful for long queries.
44
45## Parameters
46
47| Parameter | Type | Required | Default | Description |
48|--|--|--|--|--|
49| `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) |
50| `country` | string | No | `US` | Search country (2-letter country code or `ALL`) |
51| `search_lang` | string | No | `en` | Language preference (2+ char language code) |
52| `ui_lang` | string | No | `en-US` | UI language (e.g., "en-US") |
53| `count` | int | No | `20` | Number of results (1-50) |
54| `offset` | int | No | `0` | Page offset (0-9) |
55| `safesearch` | string | No | `moderate` | Adult content filter (`off`/`moderate`/`strict`) |
56| `freshness` | string | No | - | Time filter (`pd`/`pw`/`pm`/`py` or date range) |
57| `spellcheck` | bool | No | `true` | Auto-correct query |
58| `operators` | bool | No | `true` | Apply search operators |
59| `include_fetch_metadata` | bool | No | `false` | Include `fetched_content_timestamp` in results |
60
61### Freshness Values
62
63| Value | Description |
64|--|--|
65| `pd` | Past day (24 hours) |
66| `pw` | Past week (7 days) |
67| `pm` | Past month (31 days) |
68| `py` | Past year (365 days) |
69| `YYYY-MM-DDtoYYYY-MM-DD` | Custom date range |
70
71## Response Format
72
73```json
74{
75 "type": "videos",
76 "query": {
77 "original": "python tutorial",
78 "spellcheck_off": false
79 },
80 "extra": {
81 "might_be_offensive": false
82 },
83 "results": [
84 {
85 "type": "video_result",
86 "title": "Python Tutorial for Beginners",
87 "url": "https://www.youtube.com/watch?v=rfscVS0vtbw",
88 "description": "Learn Python programming from scratch...",
89 "age": "February 12, 2025",
90 "page_age": "2025-02-12T00:00:00",
91 "page_fetched": "2025-02-12T15:00:00Z",
92 "thumbnail": {
93 "src": "https://imgs.search.brave.com/...",
94 "original": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg"
95 },
96 "video": {
97 "duration": "03:45:00",
98 "views": 1523000,
99 "creator": "freeCodeCamp",
100 "publisher": "YouTube",
101 "requires_subscription": false,
102 "tags": ["python", "programming"],
103 "author": {
104 "name": "freeCodeCamp.org",
105 "url": "https://www.youtube.com/@freecodecamp"
106 }
107 },
108 "meta_url": {
109 "scheme": "https",
110 "netloc": "youtube.com",
111 "hostname": "www.youtube.com",
112 "favicon": "https://imgs.search.brave.com/...",
113 "path": "\u203a watch"
114 }
115 }
116 ]
117}
118```
119
120## Response Fields
121
122| Field | Type | Description |
123|--|--|--|
124| `type` | string | Always `"videos"` |
125| `query.original` | string | The original search query |
126| `query.altered` | string? | Spellcheck-corrected query (if changed) |
127| `query.cleaned` | string? | Cleaned/normalized query |
128| `query.spellcheck_off` | bool? | Whether spellcheck was disabled |
129| `query.show_strict_warning` | bool? | True if strict safesearch blocked adult results |
130| `query.search_operators` | object? | Applied search operators (`applied`, `cleaned_query`, `sites`) |
131| `extra.might_be_offensive` | bool | Whether results may contain offensive content |
132| `results[].type` | string | Always `"video_result"` |
133| `results[].url` | string | Source URL of the video |
134| `results[].title` | string | Video title |
135| `results[].description` | string? | Video description |
136| `results[].age` | string? | Human-readable age (e.g. "6 months ago") or absolute date (e.g. "February 12, 2025") |
137| `results[].page_age` | string? | Page age from source (ISO datetime) |
138| `results[].page_fetched` | string? | ISO datetime when page was last fetched (e.g. `2025-02-12T15:00:00Z`) |
139| `results[].fetched_content_timestamp` | int? | Fetch timestamp (only with `include_fetch_metadata=true`) |
140| `results[].video.duration` | string? | Time string (variable format) |
141| `results[].video.views` | int? | View count as integer |
142| `results[].video.creator` | string? | Channel/creator name |
143| `results[].video.publisher` | string? | Platform (YouTube, Vimeo, etc.) |
144| `results[].video.requires_subscription` | bool? | Whether video requires a subscription |
145| `results[].video.tags` | list[str]? | Tags relevant to the video |
146| `results[].video.author` | object? | Author profile |
147| `results[].video.author.name` | string | Author name |
148| `results[].video.author.url` | string | Author profile URL |
149| `results[].video.author.long_name` | string? | Extended author name |
150| `results[].video.author.img` | string? | Author profile image URL |
151| `results[].thumbnail.src` | string | Served thumbnail URL |
152| `results[].thumbnail.original` | string? | Original thumbnail URL |
153| `results[].meta_url.scheme` | string? | URL protocol scheme |
154| `results[].meta_url.netloc` | string? | Network location |
155| `results[].meta_url.hostname` | string? | Lowercased domain name |
156| `results[].meta_url.favicon` | string? | Favicon URL |
157| `results[].meta_url.path` | string? | URL path |
158
159## Search Operators
160
161Use search operators to refine results:
162- `site:youtube.com` - Limit to specific site
163- `"exact phrase"` - Match exact phrase
164- `-exclude` - Exclude term
165
166Set `operators=false` to disable operator parsing.
167
168## Use Cases
169
170- **Video content research**: Find tutorials, explainers, and reviews by topic. Use the `video.duration`, `video.views`, and `video.creator` metadata to filter and rank results programmatically. Prefer `videos-search` over `web-search` when you need a dedicated video index with richer metadata (duration, views, creator, tags) and up to 50 results per request.
171- **Fresh video monitoring**: Use `freshness=pd` or `freshness=pw` to track newly published video content on trending topics or specific subjects.
172- **Platform-specific search**: Use `site:youtube.com` or `site:vimeo.com` operators to target specific video platforms.
173- **Video metadata extraction**: Get view counts, durations, creator info, and tags for analytics, content curation, or recommendation systems.
174
175## Notes
176
177- **Pagination**: Use `offset` (0-9) with `count` for more results
178- **Max results**: Up to 50 results per request
brave