> ## Documentation Index
> Fetch the complete documentation index at: https://mindcase.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube Search

> Extract YouTube search results for a query, providing video, channel, and playlist titles, links, and descriptions

`$0.2 / 1k results`

Extract YouTube search results for a query, providing video, channel, and playlist titles, links, and descriptions

## Endpoint

`POST /api/v1/agents/youtube/search/run`

## Parameters

<ParamField body="query" type="string" required>
  **Text** · The YouTube keywords to search for.
</ParamField>

<ParamField body="type" type="string" default="video">
  **Dropdown** · Filter by content type (videos, channels, playlists).

  **Options:** `video`, `channel`, `playlist`, `movie`, `show`, `shorts`
</ParamField>

<ParamField body="maxResults" type="integer" default={50}>
  **Number** · Total results to fetch. Use 0 for all (minimum: 20).
</ParamField>

<ParamField body="sortBy" type="string">
  **Dropdown** · Sort order for the results. Relevance by default. Note: sorting is not available for Shorts.

  **Options:** `relevance`, `rating`, `date`, `views`
</ParamField>

<ParamField body="duration" type="string">
  **Dropdown** · Filter by video length.

  **Options:** `short`, `medium`, `long`
</ParamField>

<ParamField body="uploadDate" type="string">
  **Dropdown** · Restrict results to a recent time range.

  **Options:** `hour`, `today`, `week`, `month`, `year`
</ParamField>

<ParamField body="country" type="string">
  **Dropdown** · Country to search YouTube from.

  [View all 57 options →](/agents/youtube/search/values#country)
</ParamField>

<ParamField body="language" type="string">
  **Dropdown** · Language for results.

  [View all 36 options →](/agents/youtube/search/values#language)
</ParamField>

## Response columns

| Field               | Display name       | Type    |
| ------------------- | ------------------ | ------- |
| `title`             | Title              | text    |
| `description`       | Description        | text    |
| `duration`          | Duration           | text    |
| `views`             | Views              | text    |
| `publishedAt`       | Published At       | text    |
| `channel`           | Channel            | text    |
| `channelHandle`     | Channel Handle     | text    |
| `channelBadges`     | Channel Badges     | text    |
| `channelVerified`   | Channel Verified   | boolean |
| `type`              | Type               | text    |
| `thumbnail`         | Thumbnail          | url     |
| `animatedThumbnail` | Animated Thumbnail | url     |
| `channelAvatar`     | Channel Avatar     | url     |

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.mindcase.co/api/v1/agents/youtube/search/run \
    -H "Authorization: Bearer mk_live_abc123def456" \
    -H "Content-Type: application/json" \
    -d '{
    "params": {
      "query": "Automation",
      "maxResults": 20
    }
  }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.mindcase.co/api/v1/agents/youtube/search/run",
      headers={"Authorization": "Bearer mk_live_abc123def456"},
      json={"params": {
      "query": "Automation",
      "maxResults": 20
  }},
  )
  data = resp.json()
  ```
</CodeGroup>

### Example response

```json Response theme={null}
{
  "job_id": "job_7f3a2b1c",
  "status": "completed",
  "data": [
    {
      "title": "AI Automation: Complete Beginners Guide",
      "description": "Subscribe to the channel for more up-to-date beginner content! In this video tutorial, I will show you how to run any ChatGPT\u00a0...",
      "duration": "7:56",
      "views": "362575",
      "publishedAt": "2024-05-01T00:00:00Z",
      "channel": "The AI Advantage",
      "channelHandle": "@aiadvantage",
      "channelBadges": [
        "Verified"
      ],
      "channelVerified": true,
      "type": "video",
      "thumbnail": null,
      "animatedThumbnail": null,
      "channelAvatar": null
    }
  ]
}
```