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

# YouTube

> Search YouTube and get video transcripts

The YouTube tool lets an agent search videos, fetch details, and pull transcripts.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "YouTube"
        User[User] --> Agent[Agent]
        Agent --> Tool[YouTubeTool]
        Tool --> API[YouTube API]
        API --> Result[Videos]
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent input
    class Tool,API process
    class Result output
```

## Overview

YouTube tool allows you to search videos, get video details, and extract transcripts.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export YOUTUBE_API_KEY="${YOUTUBE_API_KEY:?Set YOUTUBE_API_KEY in your shell}"  # Optional for basic features
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_tools import YouTubeTool

    # Initialize
    youtube = YouTubeTool()

    # Search
    results = youtube.search("Python tutorials")
    print(results)
    ```
  </Step>

  <Step title="With Configuration">
    Use the same tool with an agent — see **Usage with Agent** below, or pass env vars and options from the sections above.
  </Step>
</Steps>

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant YouTube as YouTubeTool
    participant API as YouTube API

    User->>Agent: "Find videos about X"
    Agent->>YouTube: search(query)
    YouTube->>API: HTTPS request
    API-->>YouTube: video list
    YouTube-->>Agent: results
    Agent-->>User: final answer
```

## Usage with Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import YouTubeTool

agent = Agent(
    name="VideoResearcher",
    instructions="You help find and summarize YouTube videos.",
    tools=[YouTubeTool()]
)

response = agent.chat("Find videos about machine learning basics")
print(response)
```

## Available Methods

### search(query, max\_results=5)

Search YouTube videos.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import YouTubeTool

youtube = YouTubeTool()
videos = youtube.search("AI tutorials", max_results=5)
```

### get\_video(video\_id)

Get video details.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
video = youtube.get_video("dQw4w9WgXcQ")
```

### get\_transcript(video\_id)

Get video transcript.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
transcript = youtube.get_transcript("dQw4w9WgXcQ")
```

## Common Errors

| Error                                  | Cause              | Solution                                 |
| -------------------------------------- | ------------------ | ---------------------------------------- |
| `youtube-transcript-api not installed` | Missing dependency | Run `pip install youtube-transcript-api` |
| `Transcript not available`             | No captions        | Try different video                      |
| `Rate limited`                         | Too many requests  | Add delays                               |

## Best Practices

<AccordionGroup>
  <Accordion title="Add YOUTUBE_API_KEY for search">
    Basic transcript features work without a key, but video search needs `YOUTUBE_API_KEY`. Set it in your shell or `.env`.
  </Accordion>

  <Accordion title="Cap max_results">
    `search(query, max_results=5)` defaults to 5. Keep it low so the agent processes fewer videos per query.
  </Accordion>

  <Accordion title="Handle missing transcripts">
    Not every video has captions. Wrap `get_transcript(video_id)` in `try/except` so the agent can skip or report videos without transcripts.
  </Accordion>
</AccordionGroup>

## Related Tools

<CardGroup cols={2}>
  <Card title="Spotify" icon="book" href="/docs/tools/external/spotify">
    Music search
  </Card>

  <Card title="Wikipedia" icon="book" href="/docs/tools/external/wikipedia">
    Knowledge base
  </Card>
</CardGroup>