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

> ## Agent Instructions
> ## Agent Instructions (AIsa)
>
> - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative.
> - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key.
> - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste.
> - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`.
> - Paid calls need approval first. Docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP discovery are free to read. Before any paid, dynamically priced, or high-cost call, state the exact scope, rate, and maximum USD exposure, then wait for a separate user message approving that scope and cap. A request to collect data is not approval; do not send unapproved probes. Full rule: https://aisa.one/docs/llms.txt

# YouTube SERP

> YouTube search with ranked results and rich metadata for autonomous agents. Content gap analysis, competitor monitoring, keyword research, and region/language-specific audience research — powered by AIsa.

[View on GitHub →](https://github.com/AIsa-team/agent-skills/tree/main/social-media/youtube-serp)

**YouTube search results and rich metadata for autonomous agents.** One `AISA_API_KEY` returns ranked videos, view counts, publication dates, and thumbnails — filterable by country and language.

## Install

<CodeGroup>
  ```bash npx skills theme={null}
  npx skills add AIsa-team/agent-skills --skill youtube-serp
  ```

  ```bash AIsa CLI theme={null}
  npm install -g @aisa-one/cli
  aisa skills install youtube-serp
  ```
</CodeGroup>

Start a new agent session after installing so the skill loads.

## What can agents do with it?

<CardGroup cols={2}>
  <Card title="Content gap analysis" icon="chart-gantt">
    "Find what's ranking for 'AI agent tutorial' that our channel doesn't cover."
  </Card>

  <Card title="Competitor monitoring" icon="eye">
    "Track new uploads from the top 5 channels in this niche."
  </Card>

  <Card title="Keyword research" icon="key">
    "Which variations of 'RAG' pull the biggest view counts?"
  </Card>

  <Card title="Regional trends" icon="earth-americas">
    "Surface top ML content in Japan (jp/ja) vs. the US (us/en)."
  </Card>

  <Card title="Audience research" icon="users">
    "What thumbnails and titles work for agent demos?"
  </Card>

  <Card title="Trend spotting" icon="fire">
    "Flag videos with unusual velocity relative to channel baseline."
  </Card>
</CardGroup>

## Core capabilities

* **Keyword search** — ranked YouTube results for any query
* **Regional targeting** — `gl` (country: `us`, `jp`, `cn`, …) and `hl` (interface language: `en`, `ja`, `zh-CN`, …)
* **Rich metadata** — titles, channels, view counts, publication dates, durations, thumbnails
* **Pagination** — filter tokens for navigating beyond the first page

## Quick start

```bash theme={null}
export AISA_API_KEY="your-key"
```

### Basic search

```bash theme={null}
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+agents+tutorial" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

### Region + language

```bash theme={null}
# ML content in Japan, Japanese interface
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=machine+learning&gl=jp&hl=ja" \
  -H "Authorization: Bearer $AISA_API_KEY"

# AI trends in US, English interface
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+trends+2026&gl=us&hl=en" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

### Pagination

The response includes a pagination token you can pass back to fetch the next page:

```bash theme={null}
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+agents&sp=NEXT_PAGE_TOKEN" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

## Python client

```bash theme={null}
# Basic
python3 scripts/youtube_client.py search --query "autonomous agents"

# With country
python3 scripts/youtube_client.py search --query "coding tutorial" --country us

# With country + language
python3 scripts/youtube_client.py search --query "機械学習" --country jp --lang ja

# Top-ranking videos for a query
python3 scripts/youtube_client.py top-videos --query "AI agents tutorial" --count 5 --country us

# Competitor research
python3 scripts/youtube_client.py competitor --name "OpenAI" --topic "tutorial"
```

## Endpoint reference

| Endpoint | Method | Purpose |
| - | - | - |
| `/youtube/search` | GET | [YouTube search](/docs/api-reference/search/get_youtube-search) |

**Common parameters:**

* `engine` — always `youtube`
* `q` — search query (required)
* `gl` — country code (`us`, `jp`, `cn`, etc.)
* `hl` — language code (`en`, `ja`, `zh-CN`, etc.)
* `sp` — pagination token

## Get started

1. Sign up at [aisa.one](https://aisa.one) and create an API key in the console.
2. Set it in your shell: `export AISA_API_KEY="your-key"`.
3. Install the skill with one of the commands under [Install](#install), then start a new agent session.

## Related

<CardGroup cols={3}>
  <Card title="YouTube Search endpoint" icon="youtube" href="/docs/api-reference/search/get_youtube-search">
    Full endpoint reference with interactive playground.
  </Card>

  <Card title="Multi-source Search" icon="magnifying-glass" href="/docs/agent-skills/multi-source-search">
    Combine YouTube search with web, scholar, and Tavily.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/docs/api-reference/errors">
    Handling YouTube API-level errors.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.