# Many videos at once

Research rarely stops at one video. This tutorial expands a YouTube playlist of G-Wagon buyer videos, turns videos into one document a model can read, and searches across them.

## 1. Expand a playlist

`/items` turns a playlist, a channel or a podcast feed into a list of video references. A single video lists as itself, so you can send any input through this step.

**Expand a playlist** (`GET /api/v1/items`)

```bash
curl -G https://vid2context.com/api/v1/items \
  --data-urlencode 'url=https://www.youtube.com/playlist?list=PLHeawKfarQSPKIjpe86at3Ttc2sz7uD_b' \
  --data-urlencode limit=5
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "items": [
    {
      "input": "https://www.youtube.com/playlist?list=PLHeawKfarQSPKIjpe86at3Ttc2sz7uD_b",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:PzJL3aBRas8",
      "nativeId": "PzJL3aBRas8",
      "url": "https://www.youtube.com/watch?v=PzJL3aBRas8"
    },
    {
      "input": "https://www.youtube.com/playlist?list=PLHeawKfarQSPKIjpe86at3Ttc2sz7uD_b",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:1Xx1fmHIsiA",
      "nativeId": "1Xx1fmHIsiA",
      "url": "https://www.youtube.com/watch?v=1Xx1fmHIsiA"
    },
    {
      "input": "https://www.youtube.com/playlist?list=PLHeawKfarQSPKIjpe86at3Ttc2sz7uD_b",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:AS6LYBzFtEU",
      "nativeId": "AS6LYBzFtEU",
      "url": "https://www.youtube.com/watch?v=AS6LYBzFtEU"
    },
    {
      "input": "https://www.youtube.com/playlist?list=PLHeawKfarQSPKIjpe86at3Ttc2sz7uD_b",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:EO1PYUnXHiM",
      "nativeId": "EO1PYUnXHiM",
      "url": "https://www.youtube.com/watch?v=EO1PYUnXHiM"
    },
    {
      "input": "https://www.youtube.com/playlist?list=PLHeawKfarQSPKIjpe86at3Ttc2sz7uD_b",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:U7Dmgpp5W-Q",
      "nativeId": "U7Dmgpp5W-Q",
```

(4 more lines; run the request to see them.)
## 2. One pack for several videos

`POST /pack` takes a list of inputs and returns one Markdown document with every video's metadata, chapters and transcript, sized by `maxTokens`. Playlists in the list are expanded first. When one video fails, the others still go in, and the failure is listed under "Not included" so the model knows what is missing.

**One pack for several videos** (`POST /api/v1/pack`): Playlists in inputs are expanded. A video that fails is listed under "Not included"; the rest still go in.

```bash
curl https://vid2context.com/api/v1/pack \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "https://www.youtube.com/watch?v=cCPsdFdlshc"
  ],
  "maxTokens": 3000
}'
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
# Video context pack

This document holds the transcripts and metadata of 2 videos (18:23 in total), prepared by vid2context for an AI model to read. Each transcript paragraph starts with the time it begins in the video, in brackets; linked times open the video at that moment.

Citation rule: when you use something from a video, cite it as [Title @ m:ss](https://github.com/nirholas/vid2context/blob/main/link), using the time and link of the paragraph you drew on (or [Title @ m:ss] when the video has no link).

Some content was left out to fit a budget of 3000 tokens. Each cut is marked where it happened.

## Contents

1. [Me at the zoo](#video-1-me-at-the-zoo) (0:19)
2. [Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!](#video-2-best--worst-g-wagon-years-reliability-interiors--engines-ranked) (18:04)

## Video 1: Me at the zoo

- Channel: [jawed](https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A)
- Published: 2005-04-23
- Duration: 0:19
- Source: https://www.youtube.com/watch?v=jNQXAC9IVRw
- Language: en
- Transcript: creator captions from youtube-captions

### Description

> Microplastics are accumulating in human brains at an alarming rate
> https://www.youtube.com/watch?v=0PT5c1z3LL8
>
> “Nanoplastics and Human Health” with Matthew J Campen, PhD, MSPH

_Description shortened to 176 of 264 characters._

### Chapters

- [0:00](https://www.youtube.com/watch?v=jNQXAC9IVRw&t=0s) Intro
- [0:05](https://www.youtube.com/watch?v=jNQXAC9IVRw&t=5s) The cool thing
- [0:17](https://www.youtube.com/watch?v=jNQXAC9IVRw&t=17s) End

### Transcript

> The whole transcript, 0:01 to 0:18, is omitted for length. Fetch it with the get_section tool or the full transcript.
```

(62 more lines; run the request to see them.)
## 3. Every format in a zip

`/bundle` returns a zip: `context.md` (the pack), the transcript in each format you ask for, the metadata, and a README that tells an agent what each file is. The block lists the files; when you run it, **Download** saves the zip.

**Every format in a zip** (`GET /api/v1/bundle`): context.md is always in the zip, next to one file per format, the metadata and a README for agents.

```bash
curl -OJ -G https://vid2context.com/api/v1/bundle \
  --data-urlencode 'url=https://www.youtube.com/watch?v=jNQXAC9IVRw'
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```text
10 files, 7419 bytes

2536  me-at-the-zoo/README.md
1642  me-at-the-zoo/context.md
 218  me-at-the-zoo/transcript.txt
3608  me-at-the-zoo/context.json
 936  me-at-the-zoo/transcript.md
 415  me-at-the-zoo/transcript.srt
 534  me-at-the-zoo/transcript.vtt
1886  me-at-the-zoo/metadata.json
 254  me-at-the-zoo/chapters.md
1757  me-at-the-zoo/manifest.json
```
`POST /bundle` takes the same `inputs` list as `POST /pack` for a zip of many videos.

## 4. Find a topic across videos

`POST /research` finds where words come up in each video and returns ranked excerpts with the surrounding context and timestamp links. It reads the videos itself, so it needs nothing saved first.

**Find a topic across videos** (`POST /api/v1/research`): Ranked excerpts with context and timestamp links. Needs no saved library.

```bash
curl https://vid2context.com/api/v1/research \
  -H 'Content-Type: application/json' \
  -d '{
  "urls": [
    "https://www.youtube.com/watch?v=cCPsdFdlshc"
  ],
  "query": "reliability",
  "maxExcerpts": 3
}'
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "query": "reliability",
  "terms": [
    "reliability"
  ],
  "phrases": [],
  "results": [
    {
      "videoId": "youtube:cCPsdFdlshc",
      "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
      "channel": "Alliance Motorworks",
      "url": "https://www.youtube.com/watch?v=cCPsdFdlshc",
      "durationSec": 1084,
      "origin": "stt",
      "language": "en",
      "transcriptTokens": 5163,
      "excerpts": [
        {
          "startSec": 612.34,
          "endSec": 626.76,
          "timestamp": "[10:12]",
          "text": "I think they're very reliable. They make the right amount of power for big stuff. They make the right noises and they're very reliable. I have yet to see anything catastrophic go wrong with one of these. And I say that because we work on a ton of these and they are super reliable.",
          "context": {
            "before": "They actually started this motor in 2011 in the G550 and then kept it all the way through the 2015 model year. This is the last hurrah for the naturally aspirated 5-mile liter V8. 13 to 15 is the year range for this generation, yes? Yep. This generation. You can still get this motor in the prior generation through 2011 and 2012, but for this interior and so forth. This is a great motor. I love this motor.",
            "after": "With that, the other thing aside from the motor that is a huge technological leap forward, it's going to be your transmission. You got away from the 5-speed automatic and you go to a 7-speed automatic. I think that's just as much of a game changer in the way the truck handles and drives as the motor because it always keeps it in the right gear. And it's just, it is light years forward of where we came from. So that's on the mechanical side of things.",
            "fromSec": 589.74,
            "toSec": 647.64
          },
          "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=612s",
          "score": 2.315,
          "matched": [
            "reliability"
          ]
        },
        {
          "startSec": 994.9,
          "endSec": 999.72,
          "timestamp": "[16:34]",
          "text": "And reliability. That's it. Anything that's portion of induction is extra complexity. Yeah. Reliability.",
          "context": {
```

(37 more lines; run the request to see them.)
## 5. Search everything you have read

Every video a request has read is saved in the server's library. `/search` searches all of them at once, with `"exact phrases"` and `-excluded` words.

**Search saved transcripts** (`GET /api/v1/search`): Searches the library: every video a request above has read is saved there.

```bash
curl -G https://vid2context.com/api/v1/search \
  --data-urlencode q=elephants \
  --data-urlencode limit=5
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "hits": [
    {
      "videoId": "youtube:jNQXAC9IVRw",
      "title": "Me at the zoo",
      "startSec": 1.2,
      "endSec": 3.36,
      "text": "All right, so here we are, in front of the elephants",
      "score": 0.01639344262295082,
      "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&t=1s",
      "chapterTitle": "Intro",
      "sources": [
        "keyword"
      ],
      "snippet": "All right, so here we are, in front of the **elephants**",
      "channel": "jawed",
      "ranks": {
        "keyword": 1
      }
    }
  ],
  "meta": {
    "query": {
      "text": "elephants",
      "phrases": [],
      "excluded": []
    },
    "mode": "hybrid",
    "keyword": {
      "ran": true,
      "backend": "storage",
      "candidates": 1
    },
    "vector": "partial",
    "rerank": "off",
    "fusion": {
      "k": 60,
      "keywordWeight": 1,
      "vectorWeight": 1
    },
```

(29 more lines; run the request to see them.)
On a server with an embedding model configured, the same route also runs a vector search and merges the two lists; the response's `meta` says which sides ran.

## Next

- [Build a research collection](https://vid2context.com/docs/tutorials/collections.md): keep these videos together under one id, then pack, export and share them.
- [Cited answers and briefs](https://vid2context.com/docs/tutorials/cited-answers.md) from the same videos.
- [Many-video examples](https://vid2context.com/docs/examples/many-videos.md) on one page.
