# Search

Returns results matching required `search_term`. Optional fields select result type, duration, features, publication window, ordering, localization, and pagination.

- Platform: YouTube V2
- Request: `GET https://api.toolzerhub.com/v2/youtube/search`
- Auth: `x-api-key` header
- Cost: 1 credit per successful request. Failed requests are not billed.
- Page: https://docs.toolzerhub.com/reference/youtube-v2/search/search-you-tube

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `search_term` | query | yes | string | Text to search for. |
| `result_kind` | query | no | enum: video, channel, playlist, movie, shorts | Limit results to one content kind. |
| `length_filter` | query | no | enum: under_3_minutes, between_3_and_20_minutes, over_20_minutes | Filter videos by duration. |
| `feature_filters` | query | no | array | Comma-separated video features that every result must have. |
| `published_within` | query | no | enum: today, week, month, year | Restrict results by upload period. |
| `sort_order` | query | no | enum: relevance, popularity | Result order. Available values: relevance, popularity. |
| `region_code` | query | no | string | Two-letter country code used to localize the results. |
| `language_code` | query | no | string | Language code used to localize text and audio results. |
| `page_cursor` | query | no | string | Cursor returned by the previous response. |

## Example request

```bash
curl "https://api.toolzerhub.com/v2/youtube/search?search_term=<search_term>" \
  -H "x-api-key: $TOOLZERHUB_API_KEY"
```

Success responses are wrapped as `{ "data": ... }`. Errors return `{ "error": { "code", "status", "message", "retryable", "details" } }`. See https://docs.toolzerhub.com/docs/responses-and-errors.