# Search YouTube videos

Returns the YouTube videos that match a search, with channel, date and views. Use it to see which videos rank for a query.

Tool `youtube.search.videos` on YouTube. Contract version 1, released 2026-10-27.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/youtube.search.videos/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"coffee"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/youtube.search.videos/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"query": "coffee"}},
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/youtube.search.videos/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"query": "coffee"}}),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "youtube.search.videos",
    "input": {
      "query": "coffee"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | Yes |  | The search query. |
| `sort` | string | No | `relevance` | Order of the results: relevance (YouTube's ranking), newest, most_viewed or top_rated. One of `relevance`, `newest`, `most_viewed`, `top_rated`. |
| `time_range` | string | No |  | Only videos published in the last hour, day, week, month or year. One of `hour`, `day`, `week`, `month`, `year`. |
| `duration` | string | No |  | Only videos of this length: short (under 4 minutes), medium (4 to 20 minutes) or long (over 20 minutes). One of `short`, `medium`, `long`. |
| `next_page_token` | string | No |  | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same query, sort, time_range and duration. |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### videos

A list of rows. Always present, possibly empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | YouTube's identifier of the video. The video is at https://www.youtube.com/watch?v= followed by it. |
| `url` | string | No | Address of the video on youtube.com. |
| `title` | string | No |  |
| `snippet` | string | No | An excerpt of the video's description, as the search shows it. |
| `published_at` | string | No | When the video was published, in ISO 8601. |
| `duration_ms` | integer | No | Length of the video, in milliseconds. |
| `preview_image_url` | string | No | Address of the video's thumbnail. |
| `author_id` | string | No | YouTube's identifier of the channel that published the video, which begins with UC. |
| `author_username` | string | No | The channel's handle, without the @. |
| `author_name` | string | No | The channel's name. |
| `author_image_url` | string | No | Address of the channel's profile picture. |
| `author_verified` | boolean | No | Whether YouTube marks the channel as verified. |
| `view_count` | integer | No | Number of times the video was watched. |

### pagination

One object. Can be `null`. How to fetch the next page. Null on the last page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `next_page_token` | string | Yes | Send as next_page_token to fetch the next page. |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "videos": [
    {
      "id": "fpJL53G93lQ",
      "url": "https://www.youtube.com/watch?v=fpJL53G93lQ",
      "title": "All Coffees Explained",
      "snippet": "Every Coffee Type Explained☕️ (part 1) Subscribe For Part 2! Milk Frother - https://s.click.aliexpress.com/e/_c4s56h4b ...",
      "published_at": null,
      "duration_ms": 946000,
      "preview_image_url": "https://i.ytimg.com/vi/fpJL53G93lQ/hq720.jpg?sqp=-oaymwEjCOgCEMoBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLBPk_tBJSCUlsdgbJWGfBfHMUlMQA",
      "author_id": "UCddXepURe7TTkRWrQXwwrgw",
      "author_username": null,
      "author_name": "FooDiscover",
      "author_image_url": null,
      "author_verified": null,
      "view_count": 1551543
    },
    {
      "id": "CFzttdZe7wQ",
      "url": "https://www.youtube.com/watch?v=CFzttdZe7wQ",
      "title": "POV - My Barista Shift at the Coffee Shop",
      "snippet": "Thank you for watching this video, please consider subscribing. Espresso Machine - LA Marzocco Strada AV Grinders - Mahlkönig ...",
      "published_at": null,
      "duration_ms": 3687000,
      "preview_image_url": "https://i.ytimg.com/vi/CFzttdZe7wQ/hq720.jpg?sqp=-oaymwEjCOgCEMoBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLD28Ml4do0huFO4LL4OJ23fJK5QsA",
      "author_id": "UCqPr7D4qL-7kutOt9n68OGA",
      "author_username": null,
      "author_name": "IssackxCoffee",
      "author_image_url": null,
      "author_verified": null,
      "view_count": 1231936
    },
    {
      "id": "xb3IxAr4RCo",
      "url": "https://www.youtube.com/watch?v=xb3IxAr4RCo",
      "title": "How I Make Espresso: Tools and Techniques",
      "snippet": "Get Surfshark VPN at https://surfshark.deals/jameshoffmann and enter code 'jameshoffmann' for 83% off and 3 extra months free!",
      "published_at": null,
      "duration_ms": 1291000,
      "preview_image_url": "https://i.ytimg.com/vi/xb3IxAr4RCo/hq720.jpg?sqp=-oaymwEjCOgCEMoBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLDBKx6UVixX24L-181Odux3ll3BXQ",
      "author_id": "UCMb0O2CdPBNi-QqPk5T3gsQ",
      "author_username": null,
      "author_name": "James Hoffmann",
      "author_image_url": null,
      "author_verified": null,
      "view_count": 5162548
    }
  ],
  "pagination": {
    "next_page_token": "pt1.dGlraHViOkVwY0RFZ1pqYjJabVpXVWFqQU5EUVVGVFFXaEJRbE5DVTBOQlVYUnRZMFZ3VFU1VVRraFBWRTV6VlZsSlFrTXdUa2RsYmxJd1drWndiRTR6WkZKblowVk1aVWRKZWxOWWFFSmphbEpUVVRJdFEwRlJkRWRoYlRGdlZFaEJNazB4WkhCT1NVbENRM3BhYW1Nd1dtbFdSWEJaWVVaV1JtZG5SVXhsV0U1NFUxVTFTRTFVYUZSbFJVZERRVkYwTTFSRk1ERlpibkF3VFZob2NtTTBTVUpETTJNMFlrZG5lVlF3V21wVGVrVXdaMmRGVEZOdFJrTldXRUUxVGtSa1ZWTldWME5CVVhScVRUSm9VVlY2V2xCYVJWcHBZelJKUWtNd2VHcFZNV3hNWXpKU1lWRXdNRFJuWjBWTVZqTkdkazVZV25wVVJFNUlWa2N0UTBGUmRGQlBWbXgxVkVWYWVWUlVaRWRqTkVsQ1F6QlNhbE5ZY0VKUmFrVXlVbXRXU21kblJVeGtWbVJZVm1zMWVFNVZaRWxqUkZORFFWRjBNRlJWYUVsWFJFSnFWMnhaZEZkWlNVSkRNRVpEVFVaR1RXRnVTblpTYms1NloyZEZURk5FYXpCT1YzUnJWRE5OTVdSR1IwTkJVWFJSVmpGV1dsSkdWbXhoZWtKdllqUkpRa015ZUZkYVZUVlZZakphUlZGcVNuSnpaMFZIUTJkUlNVWkNRVU1ZZ2VEb0dDSUxjMlZoY21Ob0xXWmxaV1ElM0Q"
  }
}
```