# YouTube API guide



## Start with YouTube



Resolve a channel, find its uploads and retrieve video details or comments. Channel counts, upload rows and individual video statistics serve different purposes.



These requests use your API key and can spend credits. Check the current price on the endpoint page; each new page is a separate request. Later examples use illustrative identifiers: replace them with values from your earlier response.



### 1. Resolve the channel



You can use a handle, channelId, legacy username or supported channel URL. Keep the resolved channel ID for later calls. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/youtube/channel)



**youtube/channel**

```
curl "https://www.monocrawl.com/v1/youtube/channel?handle=%40googledevelopers" \
  -H "x-api-key: mn_your_key_here"
```



### 2. List uploads



Uploads arrive newest first. Use a returned video URL or ID for the next request. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/youtube/channel/videos)



**youtube/channel/videos**

```
curl "https://www.monocrawl.com/v1/youtube/channel/videos?handle=%40googledevelopers&max_results=25" \
  -H "x-api-key: mn_your_key_here"
```



### 3. Read video statistics



Replace the example URL with a returned upload. Upload-list metadata is not a substitute for current per-video statistics. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/youtube/video)



**youtube/video**

```
curl "https://www.monocrawl.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D9bZkp7q19f0" \
  -H "x-api-key: mn_your_key_here"
```



## Choose filters with the source behavior in mind



| Control | Behavior and limits |
| --- | --- |
| Search result types | type can contain video, channel or playlist. sortBy accepts relevance, date, rating, title or views; duration accepts short, medium or long and forces video results. uploadDate accepts hour, today, week, month or year and supplies a lookback bound. max_results is at most 50. Search snippets require detail lookups for video statistics. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/search) |
| Advanced search combinations | published_after and published_before use RFC-3339 timestamps; channel_id scopes the search to a channel. language is a preference, not a guaranteed language-only result. region supplies the source region. location is a lat,long point and requires location_radius; geographic searches use video results. Keep all bounds and filters with the cursor. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/search/advanced) |
| Channel identifiers | Provide one channelId, handle, forUsername or channel URL as supported by this endpoint. forUsername is a legacy username, not an @handle. Reuse the resolved channel ID for subsequent calls. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/channel) |
| Uploads and sort | Accepts channelId, handle or URL; max_results is at most 50. Uploads are newest first. The Data API implementation ignores sort and reports a warning: requesting popular does not create a popularity ranking. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/channel/videos) |
| Upload metadata versus statistics | channel/videos returns playlist metadata. Use each returned video ID or URL with video, or pass IDs to videos, to retrieve views, likes and duration. Private, deleted or restricted videos may be missing. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/video) |
| Comment controls | order accepts time or relevance; searchTerm filters comments. format accepts html or plainText. max_results is at most 100. Keep those options fixed when passing cursor. Reply previews have separate completeness metadata. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/video/comments) |
| Localization and totals | hl requests localized metadata where available; it is not an audience-location filter. Public subscriber counts may be rounded or hidden. Source totals and returned page counts have different meanings. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/channel) |
| Bulk lookup | Accepts up to 250 video IDs, fetched in source batches. Check missing, rejected and warnings as well as items: a successful response does not mean every requested video was found. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/youtube/videos) |



Source availability, ordering and field coverage can change. Inspect warnings and partial-result metadata alongside the rows. See [runnable workflows](https://www.monocrawl.com/docs/workflows), [metric semantics](https://www.monocrawl.com/docs/metric-semantics), [computed fields](https://www.monocrawl.com/docs/computed-fields) and the [pagination matrix](https://www.monocrawl.com/docs/pagination).



## Match the operation to your task



| Your task | Endpoint | When to use it |
| --- | --- | --- |
| Comments under a video | [`video/comments`](https://www.monocrawl.com/docs/endpoints/youtube/video/comments) | Returns top-level threads; inline replies may be only a preview. |
| Find videos, channels or playlists | [`search`](https://www.monocrawl.com/docs/endpoints/youtube/search) | Choose the result type and ordering; discovery rows have fewer details than video lookups. |
| Date, language or geographic discovery | [`search/advanced`](https://www.monocrawl.com/docs/endpoints/youtube/search/advanced) | Use explicit filters together and keep them unchanged across pages. |
| Several known video IDs | [`videos`](https://www.monocrawl.com/docs/endpoints/youtube/videos) | Inspect the endpoint’s batch size and required identifier format. |
| Spoken words | [`post-transcript`](https://www.monocrawl.com/docs/endpoints/youtube/post-transcript) | Caption availability and language depend on the video. |
| One channel and a recent sample | [`profile/full`](https://www.monocrawl.com/docs/endpoints/youtube/profile/full) | Read the bundle’s component and continuation metadata. |



Explore all documented operations by purpose below. Each endpoint reference contains its accepted parameters and current price.



### Accounts and audiences



- [`channel`](https://www.monocrawl.com/docs/endpoints/youtube/channel)

- [`profile`](https://www.monocrawl.com/docs/endpoints/youtube/profile)

- [`profile/full`](https://www.monocrawl.com/docs/endpoints/youtube/profile/full)



### Posts and media



- [`channel/playlists`](https://www.monocrawl.com/docs/endpoints/youtube/channel/playlists)

- [`channel/videos`](https://www.monocrawl.com/docs/endpoints/youtube/channel/videos)

- [`community-post`](https://www.monocrawl.com/docs/endpoints/youtube/community-post)

- [`community-posts`](https://www.monocrawl.com/docs/endpoints/youtube/community-posts)

- [`lives`](https://www.monocrawl.com/docs/endpoints/youtube/lives)

- [`playlist`](https://www.monocrawl.com/docs/endpoints/youtube/playlist)

- [`playlist/items`](https://www.monocrawl.com/docs/endpoints/youtube/playlist/items)

- [`shorts`](https://www.monocrawl.com/docs/endpoints/youtube/shorts)

- [`video`](https://www.monocrawl.com/docs/endpoints/youtube/video)

- [`video-sponsors`](https://www.monocrawl.com/docs/endpoints/youtube/video-sponsors)

- [`video/audio`](https://www.monocrawl.com/docs/endpoints/youtube/video/audio)

- [`video/files`](https://www.monocrawl.com/docs/endpoints/youtube/video/files)

- [`video/subtitles`](https://www.monocrawl.com/docs/endpoints/youtube/video/subtitles)

- [`video/thumbnails`](https://www.monocrawl.com/docs/endpoints/youtube/video/thumbnails)

- [`videos`](https://www.monocrawl.com/docs/endpoints/youtube/videos)



### Other operations



- [`channels`](https://www.monocrawl.com/docs/endpoints/youtube/channels)

- [`typeahead`](https://www.monocrawl.com/docs/endpoints/youtube/typeahead)



### Transcripts



- [`post-transcript`](https://www.monocrawl.com/docs/endpoints/youtube/post-transcript)



### Search and discovery



- [`search`](https://www.monocrawl.com/docs/endpoints/youtube/search)

- [`search/advanced`](https://www.monocrawl.com/docs/endpoints/youtube/search/advanced)

- [`search/hashtag`](https://www.monocrawl.com/docs/endpoints/youtube/search/hashtag)

- [`shorts-trending`](https://www.monocrawl.com/docs/endpoints/youtube/shorts-trending)

- [`videos/trending`](https://www.monocrawl.com/docs/endpoints/youtube/videos/trending)



### Comments and replies



- [`video/comment/replies`](https://www.monocrawl.com/docs/endpoints/youtube/video/comment/replies)

- [`video/comments`](https://www.monocrawl.com/docs/endpoints/youtube/video/comments)



## Endpoint reference

## youtube/channel

`GET /v1/youtube/channel`

Channel profile: title, handle, subscriber/view/video counts, avatar, banner and the uploads playlist id.

*YouTube channel*

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | no | Channel id (UC…). One of channelId, handle, forUsername or url is required — e.g. `UC_x5XG1OV2P6uZZ5FSM9Ttw` |
| `handle` | no | Channel @handle (with or without the @) — e.g. `@googledevelopers` |
| `forUsername` | no | Legacy channel username — e.g. `GoogleDevelopers` |
| `url` | no | Any channel URL (/channel/UC…, /@handle, /user/…, /c/…) — e.g. `https://www.youtube.com/@googledevelopers` |
| `hl` | no | BCP-47 language for localized snippet text — e.g. `en` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/channel?url=https%3A%2F%2Fwww.youtube.com%2F%40googledevelopers" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "UC_example",
  "handle": "@example_channel",
  "name": "Example Channel",
  "subscribers": 12000,
  "subscribers_hidden": false,
  "views": 840000,
  "video_count": 96
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/channel#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/channel.json)


## youtube/channel/playlists

`GET /v1/youtube/channel/playlists`

Public playlists owned by a channel: title, description, item count and privacy.

*YouTube channel playlists*

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | no | Channel id. One of channelId, handle or url is required — e.g. `UC_x5XG1OV2P6uZZ5FSM9Ttw` |
| `handle` | no | Channel @handle (resolved to a channel id first) — e.g. `@googledevelopers` |
| `url` | no | Any channel URL — e.g. `https://www.youtube.com/@googledevelopers` |
| `max_results` | no | Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `50` |
| `cursor` | no | Opaque page token from a previous response — e.g. `CAUQAA` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/channel/playlists?url=https%3A%2F%2Fwww.youtube.com%2F%40googledevelopers" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [],
  "channel_id": "example",
  "count": 0,
  "cursor": null,
  "dropped": 0,
  "has_more": false,
  "items": [
    {
      "channel": {
        "id": "example",
        "name": "example",
        "url": "https://example.com/example"
      },
      "description": "example",
      "id": "example",
      "privacy_status": "example",
      "published_at": "2026-09-01T12:00:00Z",
      "thumbnails": {
        "default": {},
        "fhd": {},
        "high": {},
        "maxres": {},
        "medium": {},
        "standard": {}
      },
      "title": "example",
      "url": "https://example.com/example",
      "video_count": 0
    }
  ],
  "total": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/channel/playlists#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/channel/playlists.json)


## youtube/channel/videos

`GET /v1/youtube/channel/videos`

Retrieve videos from the channel uploads playlist in source order. This is an uploads-playlist collection, not every channel tab; popularity sorting is not supported.

*Channel uploads*

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | no | Channel id. One of channelId, handle or url is required — e.g. `UC_x5XG1OV2P6uZZ5FSM9Ttw` |
| `handle` | no | Channel @handle — e.g. `@googledevelopers` |
| `url` | no | Any channel URL — e.g. `https://www.youtube.com/@googledevelopers` |
| `max_results` | no | Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `50` |
| `cursor` | no | Opaque page token from a previous response — e.g. `CAUQAA` |
| `sort` | no | Accepted for compatibility but ignored — uploads come newest-first (noted in _warnings) — e.g. `newest` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `sort`: Choose the documented source ordering before paging through results. Ordering keeps the normal endpoint price and does not guarantee exhaustive results.
- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/channel/videos?url=https%3A%2F%2Fwww.youtube.com%2F%40googledevelopers" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "abcdefghijk",
      "url": "https://www.youtube.com/watch?v=abcdefghijk",
      "title": "A quieter desk setup",
      "published_at": "2026-09-01T12:00:00Z"
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/channel/videos#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/channel/videos.json)


## youtube/channels

`GET /v1/youtube/channels`

Batch channel lookup — one normalized record per id; unknown/terminated ids are reported in `missing`.

*YouTube channels (batch)*

| Parameter | Required | Description |
| --- | --- | --- |
| `ids` | yes | Comma-separated (or JSON array of) channel ids; up to 250, chunked 50 per upstream call — e.g. `UC_x5XG1OV2P6uZZ5FSM9Ttw,UCrDkAvwZum-UTjHmzDI2iIw` |
| `hl` | no | BCP-47 language for localized snippet text — e.g. `en` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/channels?ids=UC_x5XG1OV2P6uZZ5FSM9Ttw%2CUCrDkAvwZum-UTjHmzDI2iIw" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "items": [
    {
      "_warnings": [
        "example"
      ],
      "avatar_url": "https://example.com/example",
      "banner_url": "https://example.com/example",
      "country": "example",
      "description": "example",
      "handle": "example",
      "id": "example",
      "keywords": "example",
      "name": "example",
      "published_at": "2026-09-01T12:00:00Z",
      "subscribers": 0,
      "subscribers_hidden": false,
      "thumbnails": {
        "default": {},
        "high": {},
        "medium": {}
      },
      "uploads_playlist_id": "example",
      "url": "https://example.com/example",
      "video_count": 0,
      "views": 0
    }
  ],
  "missing": [],
  "requested": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/channels#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/channels.json)


## youtube/community-post

`GET /v1/youtube/community-post`

One community post by URL.

*Community post*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Full community post URL. — e.g. `https://www.youtube.com/post/UgkxzJ6r7VLAK03TN5Gjq7YpjHmjtee_Rdn9` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/community-post?url=https%3A%2F%2Fwww.youtube.com%2Fpost%2FUgkxzJ6r7VLAK03TN5Gjq7YpjHmjtee_Rdn9" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "channel": {
    "id": "example",
    "title": "example"
  },
  "id": "example",
  "images": [
    "example"
  ],
  "platform": "example",
  "published": "example",
  "text": "example",
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/community-post#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/community-post.json)


## youtube/community-posts

`GET /v1/youtube/community-posts`

A channel's community-tab posts: text, images, likes and attached videos. Paged by cursor.

*Community posts*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | Channel handle without the @ (or pass channelId). — e.g. `MrBeast` |
| `channelId` | no | Channel id — alternative to handle. |
| `cursor` | no | continuationToken from the previous page. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/community-posts?handle=MrBeast" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "cursor": null,
  "dropped": 0,
  "items": [
    {
      "channel": {
        "id": "example",
        "title": "example"
      },
      "id": "example",
      "images": [
        "example"
      ],
      "platform": "example",
      "published": "example",
      "text": "example",
      "url": "https://example.com/example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/community-posts#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/community-posts.json)


## youtube/lives

`GET /v1/youtube/lives`

A channel's live tab: current and past streams with view counts and live state. Paged by cursor.

*Channel live streams*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | Channel handle without the @ (or pass channelId). — e.g. `IShowSpeed` |
| `channelId` | no | Channel id — alternative to handle. |
| `cursor` | no | continuationToken from the previous page. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/lives?handle=IShowSpeed" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "cursor": null,
  "dropped": 0,
  "items": [
    {
      "id": "example",
      "is_live": false,
      "platform": "example",
      "published": "example",
      "thumbnail": "example",
      "title": "example",
      "url": "https://example.com/example",
      "viewers": 0
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/lives#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/lives.json)


## youtube/playlist

`GET /v1/youtube/playlist`

Playlist metadata: title, description, owning channel, video count and privacy.

*YouTube playlist*

| Parameter | Required | Description |
| --- | --- | --- |
| `playlist_id` | yes | Playlist id — e.g. `PLOU2XLYxmsIKpaV8h0AGE05so0fAwwfTw` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/playlist?playlist_id=PLOU2XLYxmsIKpaV8h0AGE05so0fAwwfTw" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "channel": {
    "id": "example",
    "name": "example",
    "url": "https://example.com/example"
  },
  "description": "example",
  "id": "example",
  "privacy_status": "example",
  "published_at": "2026-09-01T12:00:00Z",
  "thumbnails": {
    "default": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "high": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "maxres": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "medium": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "standard": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    }
  },
  "title": "example",
  "url": "https://example.com/example",
  "video_count": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/playlist#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/playlist.json)


## youtube/playlist/items

`GET /v1/youtube/playlist/items`

The videos in a playlist, in playlist order, with per-item position and dates.

*YouTube playlist items*

| Parameter | Required | Description |
| --- | --- | --- |
| `playlist_id` | yes | Playlist id — e.g. `PLOU2XLYxmsIKpaV8h0AGE05so0fAwwfTw` |
| `max_results` | no | Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `50` |
| `cursor` | no | Opaque page token from a previous response — e.g. `CAUQAA` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/playlist/items?playlist_id=PLOU2XLYxmsIKpaV8h0AGE05so0fAwwfTw" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [],
  "count": 0,
  "dropped": 0,
  "has_more": false,
  "items": [
    {
      "added_to_playlist_at": "2026-09-01T12:00:00Z",
      "channel": {
        "id": "example",
        "name": "example"
      },
      "description": "example",
      "id": "example",
      "playlist_item_id": "example",
      "position": 0,
      "published_at": "2026-09-01T12:00:00Z",
      "thumbnails": {
        "default": {},
        "high": {},
        "maxres": {},
        "medium": {},
        "standard": {}
      },
      "title": "example",
      "url": "https://example.com/example"
    }
  ],
  "playlist_id": "example",
  "total": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/playlist/items#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/playlist/items.json)


## youtube/post-transcript

`GET /v1/youtube/post-transcript`

The spoken words of a YouTube video as timestamped segments plus plain text. transcript is null when the video has no captions.

*Video transcript*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Full YouTube video URL. — e.g. `https://www.youtube.com/watch?v=jNQXAC9IVRw` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/post-transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DjNQXAC9IVRw" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "has_transcript": false,
  "language": "example",
  "platform": "example",
  "segments": [
    {
      "end_ms": 0,
      "start_ms": 0,
      "text": "example"
    }
  ],
  "transcript": "example",
  "url": "https://example.com/example",
  "video_id": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/post-transcript#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/post-transcript.json)


## youtube/profile

`GET /v1/youtube/profile`

Public YouTube channel: identity, description, subscriber/video/view counts.

*YouTube channel profile*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | Channel handle, e.g. @NASA. — e.g. `@NASA` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/profile?handle=%40NASA" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "7350000000000000001",
  "handle": "example_creator",
  "name": "Example Creator",
  "followers": 12000,
  "following": 180,
  "bio": null,
  "verified": false,
  "links": [
    "https://example.com"
  ],
  "country": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/profile#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/profile.json)


## youtube/profile/full

`GET /v1/youtube/profile/full`

One-call channel dossier: channel profile, recent uploads with stats, and computed engagement analytics; per-source failures reported inline.

*YouTube profile (full)*

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | no | Channel id. One of channelId, handle or url is required — e.g. `UC_x5XG1OV2P6uZZ5FSM9Ttw` |
| `handle` | no | Channel @handle — e.g. `@googledevelopers` |
| `url` | no | Any channel URL — e.g. `https://www.youtube.com/@googledevelopers` |
| `posts` | no | Recent uploads to sample for analytics, 1-50 (default 10) — e.g. `10` |
| `cursor` | no | Opaque page token to continue the recent-uploads listing — e.g. `CAUQAA` |
| `include` | no | Comma list: videos and/or analytics (default both) — e.g. `videos,analytics` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 5 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/profile/full?url=https%3A%2F%2Fwww.youtube.com%2F%40googledevelopers" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "channel": {
    "id": "UC_example",
    "name": "Example Channel"
  },
  "recent_videos": [
    {
      "id": "abcdefghijk",
      "title": "A quieter desk setup",
      "published_at": "2026-09-01T12:00:00Z",
      "channel": {
        "id": "UC_example",
        "name": "Example Channel"
      },
      "duration_seconds": 482,
      "views": 12600,
      "likes": 640,
      "comments_count": 38
    }
  ],
  "recent_count": 1,
  "cursor": null,
  "recent_videos_pagination": {
    "returned": 1,
    "total": null,
    "has_more": false
  }
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/profile/full#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/profile/full.json)


## youtube/search

`GET /v1/youtube/search`

Search YouTube for videos, channels and playlists (Data API search.list; 100 quota units per call).

*YouTube search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search query — e.g. `lofi hip hop` |
| `type` | no | Result kinds: video, channel, playlist (comma-separable) Accepted values (comma-separated): video, channel, playlist. Case, spaces, hyphens and underscores are interchangeable. — e.g. `video` |
| `sortBy` | no | relevance, date, rating, title or views (maps to order/viewCount) Accepted values: relevance, date, rating, title, views, viewCount, viewcount. Case, spaces, hyphens and underscores are interchangeable. — e.g. `date` |
| `duration` | no | short, medium or long (forces video results) Accepted values: short, medium, long. Case, spaces, hyphens and underscores are interchangeable. — e.g. `medium` |
| `uploadDate` | no | hour/today/week/month/year — mapped to publishedAfter Accepted values: hour, lasthour, today, day, week, thisweek, month, thismonth, year, thisyear. Case, spaces, hyphens and underscores are interchangeable. — e.g. `week` |
| `region` | no | ISO-3166 region code (maps to regionCode) — e.g. `US` |
| `max_results` | no | Results per page, max 50 — e.g. `25` |
| `cursor` | no | Opaque page token from a previous response — e.g. `CAUQAA` |
| `include_metrics` | no | Opt in to one bounded video-metrics batch and one channel-handle batch at the same one-credit price. Original records, precise dates and continuation survive partial enrichment. Check data.enrichment for completion. Accepted values: true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `true` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `region`: Select the documented source market or request location. Read this endpoint’s region semantics; it does not generally prove creator residence.
- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/search?query=lofi%20hip%20hop" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "kind": "video",
      "id": "abcdefghijk",
      "url": "https://www.youtube.com/watch?v=abcdefghijk",
      "title": "A quieter desk setup",
      "channel": {
        "id": "UC_example",
        "name": "Example Channel"
      }
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/search.json)


## youtube/search/advanced

`GET /v1/youtube/search/advanced`

Advanced YouTube search exposing the Data API search.list filters (order, duration, event/type, category, geo, dates, captions and more).

*YouTube advanced search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search query — e.g. `machine learning` |
| `order` | no | relevance, date, rating, title or viewCount Accepted values: relevance, date, rating, title, viewCount. Case, spaces, hyphens and underscores are interchangeable. — e.g. `viewCount` |
| `duration` | no | short, medium or long (forces video results) Accepted values: short, medium, long. Case, spaces, hyphens and underscores are interchangeable. — e.g. `long` |
| `event_type` | no | live, upcoming or completed (forces video results) Accepted values: live, upcoming, completed. Case, spaces, hyphens and underscores are interchangeable. — e.g. `completed` |
| `license` | no | any, creativeCommon or youtube (maps to videoLicense) Accepted values: any, creativeCommon, youtube. Case, spaces, hyphens and underscores are interchangeable. — e.g. `creativeCommon` |
| `category` | no | videoCategoryId — e.g. `28` |
| `region` | no | ISO-3166 region code (maps to regionCode) — e.g. `US` |
| `language` | no | Preferred content language (maps to relevanceLanguage) — e.g. `en` |
| `published_after` | no | RFC-3339 lower bound (maps to publishedAfter) — e.g. `2024-01-01T00:00:00Z` |
| `published_before` | no | RFC-3339 upper bound (maps to publishedBefore) — e.g. `2025-01-01T00:00:00Z` |
| `channel_id` | no | Restrict to a channel (maps to channelId) — e.g. `UC_x5XG1OV2P6uZZ5FSM9Ttw` |
| `safe_search` | no | none, moderate or strict (maps to safeSearch) Accepted values: none, moderate, strict. Case, spaces, hyphens and underscores are interchangeable. — e.g. `moderate` |
| `video_caption` | no | any, closedCaption or none (maps to videoCaption) Accepted values: any, closedCaption, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `closedCaption` |
| `video_definition` | no | any, standard or high (maps to videoDefinition) Accepted values: any, standard, high. Case, spaces, hyphens and underscores are interchangeable. — e.g. `high` |
| `video_dimension` | no | 2d, 3d or any (maps to videoDimension) Accepted values: 2d, 3d, any. Case, spaces, hyphens and underscores are interchangeable. — e.g. `2d` |
| `video_embeddable` | no | true or any (maps to videoEmbeddable) Accepted values: true, any. Case, spaces, hyphens and underscores are interchangeable. — e.g. `true` |
| `video_type` | no | any, episode or movie (maps to videoType) Accepted values: any, episode, movie. Case, spaces, hyphens and underscores are interchangeable. — e.g. `movie` |
| `topic_id` | no | Freebase topic id (maps to topicId) — e.g. `/m/019_rr` |
| `location` | no | lat,long point (maps to location; requires location_radius) — e.g. `37.42307,-122.08427` |
| `location_radius` | no | Search radius, e.g. 10km (maps to locationRadius) — e.g. `10km` |
| `max_results` | no | Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `50` |
| `cursor` | no | Opaque page token from a previous response — e.g. `CAUQAA` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `region`: Select the documented source market or request location. Read this endpoint’s region semantics; it does not generally prove creator residence.
- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/search/advanced?query=machine%20learning" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "kind": "video",
      "id": "abcdefghijk",
      "url": "https://www.youtube.com/watch?v=abcdefghijk",
      "title": "A quieter desk setup",
      "channel": {
        "id": "UC_example",
        "name": "Example Channel"
      }
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/search/advanced#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/search/advanced.json)


## youtube/search/hashtag

`GET /v1/youtube/search/hashtag`

Best-effort hashtag search — a search.list keyword query for the "#tag" token (Data API has no dedicated hashtag endpoint; noted in _warnings).

*YouTube hashtag search*

| Parameter | Required | Description |
| --- | --- | --- |
| `hashtag` | yes | Hashtag with or without the leading # — e.g. `shorts` |
| `type` | no | Result kind (defaults to video) Accepted values (comma-separated): video, channel, playlist. Case, spaces, hyphens and underscores are interchangeable. — e.g. `video` |
| `max_results` | no | Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `50` |
| `cursor` | no | Opaque page token from a previous response — e.g. `CAUQAA` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/search/hashtag?hashtag=shorts" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "kind": "video",
      "id": "abcdefghijk",
      "url": "https://www.youtube.com/watch?v=abcdefghijk",
      "title": "A quieter desk setup",
      "channel": {
        "id": "UC_example",
        "name": "Example Channel"
      }
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/search/hashtag#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/search/hashtag.json)


## youtube/shorts

`GET /v1/youtube/shorts`

A channel's Shorts shelf: title, URL, views, likes and comments per short. Paged by cursor.

*Channel Shorts*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | Channel handle without the @ (or pass channelId). — e.g. `starterstory` |
| `channelId` | no | Channel id — alternative to handle. |
| `sort` | no | newest or popular. Accepted values: newest, popular. Case, spaces, hyphens and underscores are interchangeable. |
| `cursor` | no | continuationToken from the previous page. |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `sort`: Choose the documented source ordering before paging through results. Ordering keeps the normal endpoint price and does not guarantee exhaustive results.
- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/shorts?handle=starterstory" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "cursor": null,
  "dropped": 0,
  "items": [
    {
      "caption_tracks": [],
      "channel": {},
      "comments_count": 0,
      "description": "example",
      "duration_ms": 0,
      "genre": "example",
      "id": "example",
      "keywords": [],
      "likes": 0,
      "platform": "example",
      "published": "example",
      "published_at": "2026-09-01T12:00:00Z",
      "thumbnail": "example",
      "title": "example",
      "url": "https://example.com/example",
      "views": 0
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/shorts#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/shorts.json)


## youtube/shorts-trending

`GET /v1/youtube/shorts-trending`

The current trending Shorts feed with engagement counts.

*Trending Shorts*

| Parameter | Required | Description |
| --- | --- | --- |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/shorts-trending" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "caption_tracks": [],
      "channel": {
        "handle": "example",
        "id": "example",
        "title": "example",
        "url": "https://example.com/example"
      },
      "comments_count": 0,
      "description": "example",
      "duration_ms": 0,
      "genre": "example",
      "id": "example",
      "keywords": [
        "example"
      ],
      "likes": 0,
      "platform": "example",
      "published": "example",
      "published_at": "2026-09-01T12:00:00Z",
      "thumbnail": "example",
      "title": "example",
      "url": "https://example.com/example",
      "views": 0
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/shorts-trending#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/shorts-trending.json)


## youtube/typeahead

`GET /v1/youtube/typeahead`

YouTube's own search suggestions for a query — channels are identified with id and handle. Keyword-research signal.

*Search suggestions*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Partial query. — e.g. `mr beast` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/typeahead?query=mr%20beast" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "suggestions": [
    {
      "text": "example",
      "type": "example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/typeahead#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/typeahead.json)


## youtube/video

`GET /v1/youtube/video`

Full video details: title, description, duration, view/like/comment counts, thumbnails and live details.

*YouTube video*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Video URL (watch, youtu.be, /shorts/…) or a bare 11-char video id — e.g. `https://www.youtube.com/watch?v=9bZkp7q19f0` |
| `hl` | no | BCP-47 language for localized snippet text — e.g. `en` |
| `include_channel` | no | Add one bounded channel metadata lookup at the same price. Original video details survive missing enrichment; check enrichment and warnings. Accepted values: true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `true` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D9bZkp7q19f0" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "abcdefghijk",
  "title": "A quieter desk setup",
  "published_at": "2026-09-01T12:00:00Z",
  "channel": {
    "id": "UC_example",
    "name": "Example Channel"
  },
  "duration_seconds": 482,
  "views": 12600,
  "likes": 640,
  "comments_count": 38
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video.json)


## youtube/video-sponsors

`GET /v1/youtube/video-sponsors`

Detects the paid-promotion flag and infers likely sponsors from the description, links, promo codes and transcript — every sponsor carries its evidence. Experimental: absence of a detection is not proof there is no sponsor.

*Sponsor detection*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Full YouTube video URL. — e.g. `https://www.youtube.com/watch?v=AVO0ifle-OU` |
| `language` | no | Transcript language. — e.g. `en` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video-sponsors?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DAVO0ifle-OU" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "has_paid_promotion": false,
  "note": "example",
  "platform": "example",
  "promo_codes": [],
  "sponsors": [
    {
      "confidence": "example",
      "evidence": [
        {}
      ],
      "name": "example",
      "website": "example"
    }
  ],
  "url": "https://example.com/example",
  "video": {
    "channel": {
      "handle": "example",
      "id": "example",
      "title": "example"
    },
    "id": "example",
    "title": "example"
  }
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video-sponsors#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video-sponsors.json)


## youtube/video/audio

`GET /v1/youtube/video/audio`

The audio-only streams the platform offers for a video: format tag, direct time-limited link, MIME type, bitrate, sample rate, channels and duration. Links expire; fetch them promptly.

*YouTube video audio streams*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Video URL or id — e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video/audio?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "count": 0,
  "has_more": false,
  "items": [
    {
      "audio_channels": 0,
      "audio_quality": "example",
      "audio_sample_rate": 0,
      "average_bitrate": 0,
      "bitrate": 0,
      "content_length": 0,
      "duration_ms": 0,
      "itag": 0,
      "last_modified": "example",
      "mime_type": "example",
      "quality": "example",
      "url": "https://example.com/example"
    }
  ],
  "note": "example",
  "url": "https://example.com/example",
  "video_id": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video/audio#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video/audio.json)


## youtube/video/comment/replies

`GET /v1/youtube/video/comment/replies`

Replies under a specific top-level comment, addressed by the parent comment id.

*YouTube comment replies*

| Parameter | Required | Description |
| --- | --- | --- |
| `comment_id` | yes | Top-level (parent) comment id whose replies to fetch. the reference catalogue continuationToken is accepted as this id — e.g. `Ugz1234567890AbCdEf4AaABAg` |
| `format` | no | html or plainText comment text (maps to textFormat) Accepted values: html, plainText. Case, spaces, hyphens and underscores are interchangeable. — e.g. `plainText` |
| `max_results` | no | Requested page size, 1–100. The paid primary defaults to 100; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `100` |
| `cursor` | no | Opaque page token from a previous response — e.g. `QURTSl9pMg` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video/comment/replies?comment_id=Ugz1234567890AbCdEf4AaABAg" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [],
  "count": 0,
  "cursor": null,
  "dropped": 0,
  "has_more": false,
  "items": [
    {
      "author": {
        "avatar_url": "https://example.com/example",
        "channel_id": "example",
        "channel_url": "https://example.com/example",
        "name": "example"
      },
      "id": "example",
      "likes": 0,
      "parent_id": "example",
      "published_at": "2026-09-01T12:00:00Z",
      "text": "example",
      "text_original": "example",
      "updated_at": "2026-09-01T12:00:00Z"
    }
  ],
  "parent_id": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video/comment/replies#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video/comment/replies.json)


## youtube/video/comments

`GET /v1/youtube/video/comments`

Top-level comment threads on a video; comments-disabled videos surface as 404.

*YouTube video comments*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Video URL or a bare 11-char video id — e.g. `https://www.youtube.com/watch?v=9bZkp7q19f0` |
| `order` | no | time for newest first, or relevance for top comments first Accepted values: time, relevance. Case, spaces, hyphens and underscores are interchangeable. — e.g. `relevance` |
| `searchTerm` | no | Only comments matching this word or phrase — e.g. `great video` |
| `format` | no | html or plainText comment text Accepted values: html, plainText. Case, spaces, hyphens and underscores are interchangeable. — e.g. `plainText` |
| `max_results` | no | Requested page size, 1–100. The paid primary defaults to 100; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `100` |
| `cursor` | no | Opaque page token from a previous response — e.g. `QURTSl9pMg` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video/comments?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D9bZkp7q19f0" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "example_comment",
      "text": "Useful guide",
      "likes": 3,
      "reply_count": 2,
      "replies": [],
      "replies_pagination": {
        "returned": 0,
        "total": 2,
        "complete": false,
        "has_more": true
      }
    }
  ],
  "cursor": null,
  "has_more": null,
  "total": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video/comments#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video/comments.json)


## youtube/video/files

`GET /v1/youtube/video/files`

The video stream files the platform offers for a video: format tag, direct time-limited link, MIME type, quality label, size, frame rate, bitrate and duration. Links expire; fetch them promptly.

*YouTube video stream files*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Video URL or id — e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video/files?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "count": 0,
  "has_more": false,
  "items": [
    {
      "audio_channels": 0,
      "audio_quality": "example",
      "audio_sample_rate": 0,
      "average_bitrate": 0,
      "bitrate": 0,
      "content_length": 0,
      "duration_ms": 0,
      "fps": 0,
      "height": 0,
      "itag": 0,
      "last_modified": "example",
      "mime_type": "example",
      "quality": "example",
      "url": "https://example.com/example",
      "width": 0
    }
  ],
  "note": "example",
  "url": "https://example.com/example",
  "video_id": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video/files#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video/files.json)


## youtube/video/subtitles

`GET /v1/youtube/video/subtitles`

The caption tracks a video carries: language code and name, whether auto-generated, and the track link. The transcript text itself is youtube/post-transcript.

*YouTube caption tracks*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Video URL or id — e.g. `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
| `language` | no | Restrict to one language code — e.g. `en` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video/subtitles?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "has_more": false,
  "items": [
    {
      "language_code": "example",
      "language_name": "example",
      "url": "https://example.com/example"
    }
  ],
  "note": "example",
  "url": "https://example.com/example",
  "video_id": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video/subtitles#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video/subtitles.json)


## youtube/video/thumbnails

`GET /v1/youtube/video/thumbnails`

A video's thumbnail set from the snippet, plus conventional i.ytimg.com URLs for every size.

*YouTube video thumbnails*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Video URL or a bare 11-char video id — e.g. `https://www.youtube.com/watch?v=9bZkp7q19f0` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/video/thumbnails?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D9bZkp7q19f0" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "best_url": "https://example.com/example",
  "derived_urls": {
    "default": "example",
    "high": "example",
    "maxres": "example",
    "medium": "example",
    "standard": "example"
  },
  "thumbnails": {
    "default": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "high": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "maxres": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "medium": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    },
    "standard": {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    }
  },
  "title": "example",
  "video_id": "example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/video/thumbnails#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/video/thumbnails.json)


## youtube/videos

`GET /v1/youtube/videos`

Batch video lookup — one normalized record per id; unknown/private/deleted ids are reported in `missing`.

*YouTube videos (batch)*

| Parameter | Required | Description |
| --- | --- | --- |
| `ids` | yes | Comma-separated (or JSON array of) video ids or URLs; up to 250, chunked 50 per upstream call — e.g. `9bZkp7q19f0,kJQP7kiw5Fk` |
| `hl` | no | BCP-47 language for localized snippet text — e.g. `en` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/videos?ids=9bZkp7q19f0%2CkJQP7kiw5Fk" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "abcdefghijk",
      "title": "A quieter desk setup",
      "published_at": "2026-09-01T12:00:00Z",
      "channel": {
        "id": "UC_example",
        "name": "Example Channel"
      },
      "duration_seconds": 482,
      "views": 12600,
      "likes": 640,
      "comments_count": 38
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/videos#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/videos.json)


## youtube/videos/trending

`GET /v1/youtube/videos/trending`

The most-popular videos chart (videos.list chart=mostPopular) for a region and optional category.

*YouTube trending videos*

| Parameter | Required | Description |
| --- | --- | --- |
| `region` | no | ISO-3166 region code (default US; maps to regionCode) — e.g. `US` |
| `category` | no | videoCategoryId to restrict the chart — e.g. `10` |
| `language` | no | Localized text language (maps to hl) — e.g. `en` |
| `max_results` | no | Requested page size, 1–50. The paid primary defaults to 50; the source may return fewer. Keep an explicit size unchanged while paginating. — e.g. `50` |
| `cursor` | no | Opaque page token from a previous response — e.g. `CAUQAA` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `region`: Select the documented source market or request location. Read this endpoint’s region semantics; it does not generally prove creator residence.
- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/youtube/videos/trending" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "cursor": null,
  "dropped": 0,
  "has_more": false,
  "items": [
    {
      "category_id": "example",
      "channel": {
        "id": "example",
        "name": "example",
        "url": "https://example.com/example"
      },
      "comments_count": 0,
      "default_language": "example",
      "definition": "example",
      "description": "example",
      "dimension": "example",
      "duration": "example",
      "duration_seconds": 0,
      "embeddable": false,
      "favorites": 0,
      "has_captions": false,
      "id": "example",
      "licensed_content": false,
      "likes": 0,
      "live_broadcast_content": "example",
      "made_for_kids": false,
      "privacy_status": "example",
      "projection": "example",
      "published_at": "2026-09-01T12:00:00Z",
      "tags": [
        "example"
      ],
      "thumbnails": {
        "default": {},
        "fhd": {},
        "high": {},
        "maxres": {},
        "medium": {},
        "qhd": {},
        "standard": {},
        "uhd": {}
      },
      "title": "example",
      "url": "https://example.com/example",
      "views": 0
    }
  ],
  "region": "example",
  "total": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/youtube/videos/trending#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/youtube/videos/trending.json)