# Video search

`GET` `/v1/videos/search`

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

**Base URL:** `https://api.search.brave.com/res`

## Authorization

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `x-subscription-token` | header | string | Yes |  | The subscription token that was generated for the product. |

## Query Parameters

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `q` | query | string | Yes |  | The user's search query term. Query can not be empty. Maximum of 400 characters and 50 words in the query. |
| `search_lang` | query | string | No | `ar`, `eu`, `bn`, `bg`, `ca`, `zh-hans`, `zh-hant`, `hr`, `cs`, `da`, `nl`, `en`, `en-gb`, `et`, `fi`, `fr`, `gl`, `de`, `el`, `gu`, `he`, `hi`, `hu`, `is`, `it`, `ja`, `jp`, `kn`, `ko`, `lv`, `lt`, `ms`, `ml`, `mr`, `nb`, `pl`, `pt-br`, `pt-pt`, `pa`, `ro`, `ru`, `sr`, `sk`, `sl`, `es`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `vi`; default `en` | The search language preference. The 2 or more character language code for which the search results are provided. |
| `ui_lang` | query | string | No | `es-AR`, `en-AU`, `de-AT`, `nl-BE`, `fr-BE`, `pt-BR`, `en-CA`, `fr-CA`, `es-CL`, `da-DK`, `fi-FI`, `fr-FR`, `de-DE`, `el-GR`, `zh-HK`, `en-IN`, `en-ID`, `it-IT`, `ja-JP`, `ko-KR`, `en-MY`, `es-MX`, `nl-NL`, `en-NZ`, `no-NO`, `zh-CN`, `pl-PL`, `en-PH`, `ru-RU`, `en-ZA`, `es-ES`, `sv-SE`, `fr-CH`, `de-CH`, `zh-TW`, `tr-TR`, `en-GB`, `en-US`, `es-US`; default `en-US` | User interface language preferred in response. Usually of the format `<language_code>-<country_code>`. For more, see [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept-language). |
| `country` | query | string | No | `AR`, `AU`, `AT`, `BE`, `BR`, `CA`, `CL`, `DK`, `FI`, `FR`, `DE`, `GR`, `HK`, `IN`, `ID`, `IT`, `JP`, `KR`, `MY`, `MX`, `NL`, `NZ`, `NO`, `CN`, `PL`, `PT`, `PH`, `RU`, `SA`, `ZA`, `ES`, `SE`, `CH`, `TW`, `TR`, `GB`, `US`, `ALL`; default `US` | 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. |
| `safesearch` | query | string | No | `off`, `moderate`, `strict`; default `moderate` | 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. |
| `count` | query | integer | No | `1`-`50`; default `20` | 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. |
| `offset` | query | integer | No | `0`-`9`; default `0` | 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. |
| `spellcheck` | query | boolean | No | default `true` | 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. |
| `freshness` | query | string | No | default `` | 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`. |
| `include_fetch_metadata` | query | boolean | No | default `false` | Include fetch metadata. |
| `operators` | query | boolean | No | default `true` | Whether to apply search operators. |

## Headers

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `api-version` | header | string | No |  | 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](/documentation/guides/versioning). |
| `accept` | header | string | No | `application/json`, `*/*`; default `application/json` | The default supported media type is application/json. |
| `cache-control` | header | string | No | `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` | header | string | No |  | 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](https://www.rfc-editor.org/rfc/rfc9110.html#name-user-agent). |

## Responses

### 200
Successful Response

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `query` | object | Video search query string. |
| `query.original` | string | The original query that was requested. |
| `query.altered` | string? | The altered query by the spellchecker. This is the query that is used to search if any. |
| `query.cleaned` | string? | The cleaned normalized query by the spellchecker. This is the query that is used to search if any. |
| `query.spellcheck_off` | bool? | Whether the spellchecker is enabled or disabled. |
| `query.show_strict_warning` | bool? | 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? | Search operators applied to the query. |
| `query.search_operators.applied` | bool? | Whether search operators were applied to the query. |
| `query.search_operators.cleaned_query` | string? | The query after search operators have been processed. |
| `query.search_operators.sites` | string[]? | List of site domains extracted from site: operators. |
| `results` | object[]? | The list of video results for the given query. |
| `results[].type` | string? | The type of video search API result. The value is always `video_result`. |
| `results[].url` | string | The source URL of the video. |
| `results[].title` | string | The title of the video. |
| `results[].description` | string? | The description for the video. |
| `results[].age` | string? | A human-readable representation of the video's age. For example, `2 days ago`. |
| `results[].page_age` | string? | The page's date, based on its published or last modified date. |
| `results[].page_fetched` | string? | The ISO date time when the page was last fetched. The format is `YYYY-MM-DDTHH:MM:SSZ`. |
| `results[].fetched_content_timestamp` | int? | The timestamp when the content was fetched. |
| `results[].video` | object? | Metadata for the video. |
| `results[].video.duration` | string? | A time string representing the duration of the video. |
| `results[].video.views` | int? | The number of views of the video. |
| `results[].video.creator` | string? | The creator of the video. |
| `results[].video.publisher` | string? | The publisher of the video. |
| `results[].video.requires_subscription` | bool? | Whether the video requires a subscription. |
| `results[].video.tags` | string[]? | A list of tags relevant to the video. |
| `results[].video.author` | object? | A profile associated with the video. |
| `results[].video.author.name` | string | The name of the profile. |
| `results[].video.author.url` | string | The original URL where the profile is available. |
| `results[].video.author.long_name` | string? | The long name of the profile. |
| `results[].video.author.img` | string? | The served image URL representing the profile. |
| `results[].meta_url` | object? | Aggregated information on the URL associated with the video search result. |
| `results[].meta_url.scheme` | string? | The protocol scheme extracted from the URL. |
| `results[].meta_url.netloc` | string? | The network location part extracted from the URL. |
| `results[].meta_url.hostname` | string? | The lowercased domain name extracted from the URL. |
| `results[].meta_url.favicon` | string? | The favicon used for the URL. |
| `results[].meta_url.path` | string? | The hierarchical path of the URL useful as a display string. |
| `results[].thumbnail` | object? | The thumbnail for the video. |
| `results[].thumbnail.src` | string | The served URL of the thumbnail associated with the video. |
| `results[].thumbnail.original` | string? | The original URL of the thumbnail associated with the video. |
| `extra` | object | Additional information about the video search results. |
| `extra.might_be_offensive` | bool? | Indicates whether the video search results might contain offensive content. |

### 404
Not Found

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

### 422
Unprocessable Entity

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

### 429
Too Many Requests

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

## Code Samples

### cURL

```bash
curl "https://api.search.brave.com/res/v1/videos/search?q=machine+learning+tutorial" \
  -H "Accept: application/json" \ 
  -H "Accept-Encoding: gzip" \ 
  -H "X-Subscription-Token: <YOUR_API_KEY>"
```

### Python

```python
import requests

url = "https://api.search.brave.com/res/v1/videos/search"

params = {
    "q": "machine learning tutorial"
}

headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "<YOUR_API_KEY>"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```