# YouTube search with metrics

Add include_metrics=true to search for video metrics and channel handles at the normal one-credit price. The option preserves the original search records, precise publish dates and continuation.

## One-credit enriched search

```
GET /v1/youtube/search?query=space%20exploration&type=video&include_metrics=true
```

Video rows gain `metrics.views`, `metrics.likes`, `metrics.comments` and `metrics.duration_seconds`. `channel.handle` is supplied when available. Zero stays zero; unavailable fields stay null.

Check `data.enrichment.metrics` and `data.enrichment.channels`: `ok`, `partial`, `unavailable` or `not_needed`. Metrics marked `ok` have views and duration for every distinct returned video; optional engagement counts can still be null. An optional lookup failure retains the search page and adds a warning. A fallback source may omit enrichment entirely and provide a warning.

Each request uses at most one video batch and one channel batch. Keep the same inputs and `include_metrics=true` when following the cursor. Search without the option keeps its existing response and cost.

For a creator’s verification and external links, use [youtube/profile](https://www.monocrawl.com/docs/endpoints/youtube/profile) with a handle. `verified` and `links` are source-reported and nullable. The separate [channel lookup](https://www.monocrawl.com/docs/endpoints/youtube/channel) retains its existing precise dates and upload metadata.

## Preview, then run

The separate [Node.js batch workflow](https://www.monocrawl.com/examples/youtube-search-metrics.mjs) remains available when you want to control which videos receive a detail lookup. It uses the normal component prices. With Node.js 22 or newer, set `MONOCRAWL_API_KEY` and run a free estimate:

```
node youtube-search-metrics.mjs '{"query":"space exploration","maxResults":25,"maxVideos":25,"maxCredits":3,"estimateOnly":true}'
```

Remove `estimateOnly` to execute. The workflow uses the public GET endpoints with your key. It checks both prices before spending, checks again before each request, and sends a per-call `X-Max-Credits` ceiling. Choose `maxCredits` using the current estimate.

`maxResults` accepts 1–50 and defaults to 25. `maxVideos` accepts 0–50 and defaults to 50; zero runs search only. One run reads one search page and at most one batch of distinct video IDs. It never fans out into one lookup per video.

## Read the enriched results

Each search row retains its existing fields and gains `metrics`: `views`, `likes`, `comments` and `duration_seconds`. A measured zero stays zero; unavailable values stay null. `metrics_status` explains whether the lookup succeeded, was unrequested, unavailable or failed.

The join uses the exact video ID and never overwrites `published_at`. Rows retain their order even if the batch answers in a different order, omits a private video or fails. The returned `cursor` and `has_more` still describe the search page; pass the cursor back with the same query and key for another explicitly priced run.

Ordinary [youtube/search](https://www.monocrawl.com/docs/endpoints/youtube/search) requests keep their existing response and cost. This downloadable helper adds the batch only when you run it.

## Costs and partial results

| Component | Current base price |
| --- | --- |
| [`youtube/search`](https://www.monocrawl.com/docs/endpoints/youtube/search) | 1 credits |
| [`youtube/videos`](https://www.monocrawl.com/docs/endpoints/youtube/videos) | 2 credits |

The maximum is one search price plus one GET video-batch price. Empty searches skip the batch, and cache hits can lower the charge. The helper reports its ledger and confirmed credits. `maxDurationSeconds` defaults to 90 and accepts 1–180.

A missing paid response stops the workflow without automatic retries, retains that request’s maximum charge under `credits_reserved_unknown`, and reports a partial result. Check account usage before retrying. A successful search remains charged if a later enrichment fails.