Videos Search

Search video content from a large independent index of web pages.

View skill file Skill file for Video search

Authorization

x-subscription-token string header required
The subscription token that was generated for the product.

Request Body required

q string required
The user’s search query term. Query can not be empty. Maximum of 400 characters and 50 words in the query.
search_lang enum<string>
The search language preference. The 2 or more character language code for which the search results are provided.
Default: "en"
Available options: areubn
ui_lang enum<string>
User interface language preferred in response. Usually of the format <language_code>-<country_code>. For more, see RFC 9110.
Default: "en-US"
Available options: es-ARen-AUde-AT
country enum<string>
The search query country, where the results come from. The country string is limited to 2 character country codes of supported countries or ALL for worldwide.
Default: "US"
Available options: ARAUAT
safesearch enum<string>

Filters search results for adult content. The following values are supported:

  • off - No filtering is done.
  • moderate - Filters explicit content, like images and videos, but allows adult domains in the search results.
  • strict - Drops all adult content from search results.
Default: "moderate"
Available options: offmoderatestrict
count integer
The number of search results returned in response. The maximum is 50. The actual number delivered may be less than requested. Combine this parameter with offset to paginate search results.
Min: 1 Max: 50 Default: 20
offset integer
The zero based offset that indicates number of search results per page (count) to skip before returning the result. The maximum is 9. The actual number delivered may be less than requested based on the query. In order to paginate results use this parameter together with count. For example, if your user interface displays 20 search results per page, set count to 20 and offset to 0 to show the first page of results. To get subsequent pages, increment offset by 1 (e.g. 0, 1, 2). The results may overlap across multiple pages.
Min: 0 Max: 9 Default: 0
spellcheck boolean
Whether to spell check the provided query. If the spellchecker is enabled, the modified query is always used for search. The modified query can be found in altered key from the query response model.
Default: true
freshness string

Filters search results by page age. The age of a page is determined by the most relevant date reported by the content, such as its published or last modified date. The following values are supported:

  • pd - Pages aged 24 hours or less.
  • pw - Pages aged 7 days or less.
  • pm - Pages aged 31 days or less.
  • py - Pages aged 365 days or less.
  • YYYY-MM-DDtoYYYY-MM-DD - A custom date range is also supported by specifying start and end dates e.g. 2022-04-01to2022-07-30.
Default: ""
include_fetch_metadata boolean
Include fetch metadata.
Default: false
operators boolean
Whether to apply search operators.
Default: true

Headers

api-version string
The API version to use. This is denoted by the format YYYY-MM-DD. Default is the latest that is available. Read more about API versioning.
accept enum<string>
The default supported media type is application/json.
Default: "application/json"
Available options: application/json*/*
cache-control "no-cache"
Brave Search will return cached content by default. To prevent caching set the Cache-Control header to no-cache. This is currently done as best effort.
user-agent string
  • Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.71 Mobile Safari/537.36 Android
  • Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/103.0.5060.63 Mobile/15E148 Safari/604.1 iOS
  • Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36 macOS
  • Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36 Windows
The user agent originating the request. Brave search can utilize the user agent to provide a different experience depending on the device as described by the string. The user agent should follow the commonly used browser agent strings on each platform. For more information on curating user agents, see RFC 9110.

Responses

200 Successful Response
type "videos"
Default: "videos"
query object required
Video search query string.
query.original string required
The original query that was requested.
query.altered string nullable
The altered query by the spellchecker. This is the query that is used to search if any.
query.cleaned string nullable
The cleaned normalized query by the spellchecker. This is the query that is used to search if any.
query.spellcheck_off boolean nullable
Whether the spellchecker is enabled or disabled.
query.show_strict_warning boolean nullable
The value is true if the lack of results is due to a strict safesearch setting. Adult content relevant to the query was found, but was blocked by safesearch.
query.search_operators object nullable
Search operators applied to the query.
query.search_operators.applied boolean
Whether search operators were applied to the query.
Default: false
query.search_operators.cleaned_query string nullable
The query after search operators have been processed.
query.search_operators.sites string[] nullable
List of site domains extracted from site: operators.
results object[]
The list of video results for the given query.
Default: []
results.type "video_result"
The type of video search API result. The value is always video_result.
Default: "video_result"
results.url string required
The source URL of the video.
results.title string required
The title of the video.
results.description string nullable
The description for the video.
results.age string nullable
A human-readable representation of the video’s age. For example, 2 days ago.
results.page_age string nullable
The page’s date, based on its published or last modified date.
results.page_fetched string nullable
The ISO date time when the page was last fetched. The format is YYYY-MM-DDTHH:MM:SSZ.
results.fetched_content_timestamp integer nullable
The timestamp when the content was fetched.
results.video object nullable
Metadata for the video.
results.video.duration string nullable
A time string representing the duration of the video.
results.video.views integer nullable
The number of views of the video.
results.video.creator string nullable
The creator of the video.
results.video.publisher string nullable
The publisher of the video.
results.video.requires_subscription boolean nullable
Whether the video requires a subscription.
results.video.tags string[] nullable
A list of tags relevant to the video.
results.video.author object nullable
A profile associated with the video.
results.meta_url object nullable
Aggregated information on the URL associated with the video search result.
results.meta_url.scheme string nullable
The protocol scheme extracted from the URL.
results.meta_url.netloc string nullable
The network location part extracted from the URL.
results.meta_url.hostname string nullable
The lowercased domain name extracted from the URL.
results.meta_url.favicon string nullable
The favicon used for the URL.
results.meta_url.path string nullable
The hierarchical path of the URL useful as a display string.
results.thumbnail object nullable
The thumbnail for the video.
results.thumbnail.src string required
The served URL of the thumbnail associated with the video.
results.thumbnail.original string nullable
The original URL of the thumbnail associated with the video.
extra object required
Additional information about the video search results.
extra.might_be_offensive boolean
Indicates whether the video search results might contain offensive content.
Default: false
404 Not Found
type string
Default: "ErrorResponse"
error object required
error.id string required
A unique identifier for this particular occurrence of the problem.
error.status integer required
The HTTP status code applicable to this problem, expressed as a string value.
error.detail string nullable
Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
error.meta object nullable
A meta object containing non-standard meta-information about the error.
error.code enum<string> required
An application-specific error code, expressed as a string value.
Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED
time integer
Default: 0
422 Unprocessable Entity
type string
Default: "ErrorResponse"
error object required
error.id string required
A unique identifier for this particular occurrence of the problem.
error.status integer required
The HTTP status code applicable to this problem, expressed as a string value.
error.detail string nullable
Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
error.meta object nullable
A meta object containing non-standard meta-information about the error.
error.code enum<string> required
An application-specific error code, expressed as a string value.
Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED
time integer
Default: 0
429 Too Many Requests
type string
Default: "ErrorResponse"
error object required
error.id string required
A unique identifier for this particular occurrence of the problem.
error.status integer required
The HTTP status code applicable to this problem, expressed as a string value.
error.detail string nullable
Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
error.meta object nullable
A meta object containing non-standard meta-information about the error.
error.code enum<string> required
An application-specific error code, expressed as a string value.
Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED
time integer
Default: 0