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

# Youtube

> Search videos, channels, comments, and transcripts on Youtube via Nephia.

Youtube endpoints live under `/v1/youtube/*`. See the [API Reference](/api-reference/overview) for the full endpoint list. Credit rates are in [Credits](/credits#youtube).

## Pagination

Search, channel uploads, and comment endpoints return an opaque `nextCursor`. Pass it back unchanged on the next request.

## Region (`gl`)

Optional `gl` selects the residential proxy region (default `US`). Allowed values are on `GET /v1/youtube/regions` (0 credits). `hl` is fixed to `en` and is not a public parameter.

## Search

`GET /v1/youtube/search` takes `q` (required), optional `cursor`, and optional `gl`. Returns `videos[]` with canonical video objects and optional `nextCursor`.

`POST /v1/youtube/search` accepts a JSON body `{ query, cursor?, gl? }` with the same response shape. The [Node SDK](/sdk) uses `query` for both `search.list()` and `search.create()` (GET maps to `q` on the wire).

Both routes cost **5 credits per page**. See [Credits — Youtube](/credits#youtube).

## Videos

`GET /v1/youtube/videos/:id` returns one video (10 credits). Shorts ids (`/shorts/…`) are accepted; responses use the watch URL shape.

`GET /v1/youtube/videos/:id/comments` paginates with `cursor` (5 credits per page). Replies are not expanded in MVP.

`GET /v1/youtube/videos/:id/captions` lists caption tracks (2 credits).

`GET /v1/youtube/videos/:id/transcript?lang=` returns transcript segments (5 credits). Optional `lang` selects a track; omit to use the default.

Credit rates for all video routes are in [Credits — Youtube](/credits#youtube).

## Channels

`GET /v1/youtube/channels/:id` accepts a channel id (`UC…`) or handle (`@name`).

`GET /v1/youtube/channels/:id/videos` lists uploads with cursor pagination.

`GET /v1/youtube/channels/resolve?q=` resolves a handle or search string to a channel (2 credits).

## Reference

`GET /v1/youtube/regions` returns the allowed `gl` values (0 credits).

## Not found

Missing video, channel, captions, or transcript returns HTTP **404** with `NOT_FOUND`. Upstream or parse failures return **503**. Youtube does not expose granular soft-404 codes like Reddit or X — credits are still charged for definitive 404s on billed endpoints.

## Watches

Youtube watches poll **either** search **or** channel uploads — provide `query` **or** `channel` (handle or id), not both. Both → HTTP 400.

Interval: **60–3600** seconds. Cap: **20** active watches per Account.

Each poll tick costs **5 credits**. The first tick establishes a silent baseline (no events). Subsequent ticks emit `video.created` webhooks with the full video object. See [Watches](/watches) and [Webhooks](/webhooks).

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/youtube/watches \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "web scraping tutorial",
    "refresh_interval_seconds": 300,
    "webhook_url": "https://example.com/webhooks/nephia"
  }'
```