# YouTube

Measured YouTube data, one operation per call. Channels come from evidence (a pasted channel URL, an @handle you SAW, a UC… id) — never typed from a person's name. ops: channels (subjects = @handles, UC ids or channel URLs; add include.videos to get each channel's recent videos IN THE SAME CALL), videos (one channel, deep — includes the channel card when held; views, likes, comments, duration and absolute publish dates per video), comments (top comments on videos by watch/shorts URL or id), history (stored subscriber/video/view series, free). Ops are independent — issue several as PARALLEL tool calls. Fresh fetches cost credits; anything already held is free.

`POST https://api.zomler.com/api/v1/platforms/youtube`

-   [channels](#channels)
-   [videos](#videos)
-   [comments](#comments)
-   [history](#history)

## channels

from 1 credit · fresh for 7 days

Channel cards for up to ten channels, by @handle, UC… id or pasted channel URL. `include.videos` adds each channel's recent videos to the same answer.

### Request fields

| Field | Type | Default | Values / limits |
| --- | --- | --- | --- |
| `subjects` (required) | list of string | — | 1-10 items |
| `include` | object | `—` | — |
| `include.videos` | object | `—` | — |
| `include.videos.limit` | integer | `10` | 1-50 |
| `include.videos.since` | string | `—` | YYYY-MM-DD |

### Example

```bash
curl -X POST https://api.zomler.com/api/v1/platforms/youtube \
  -H "X-API-Key: zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "op": "channels",
    "subjects": [
      "example"
    ]
  },
  "estimateOnly": false
}'
```

```js
const res = await fetch("https://api.zomler.com/api/v1/platforms/youtube", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ZOMLER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "request": {
      "op": "channels",
      "subjects": [
        "example"
      ]
    },
    "estimateOnly": false
  }),
});
const envelope = await res.json();
console.log(envelope.data, envelope.cost.creditsCharged);
```

```python
import os, httpx

res = httpx.post(
    "https://api.zomler.com/api/v1/platforms/youtube",
    headers={"X-API-Key": os.environ["ZOMLER_API_KEY"]},
    json={
      "request": {
        "op": "channels",
        "subjects": [
          "example"
        ]
      },
      "estimateOnly": False
    },
    timeout=120,
)
envelope = res.json()
print(envelope["data"], envelope["cost"]["creditsCharged"])
```

## videos

from 5 credits for 10 · fresh for 2 days

One channel's recent videos with views, likes and comments — includes the channel card when held. A date floor always fetches fresh.

### Request fields

| Field | Type | Default | Values / limits |
| --- | --- | --- | --- |
| `subject` (required) | string | — | ≤400 chars |
| `limit` | integer | `10` | 1-50 |
| `since` | string | `—` | YYYY-MM-DD |

### Example

```bash
curl -X POST https://api.zomler.com/api/v1/platforms/youtube \
  -H "X-API-Key: zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "op": "videos",
    "subject": "example"
  },
  "estimateOnly": false
}'
```

```js
const res = await fetch("https://api.zomler.com/api/v1/platforms/youtube", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ZOMLER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "request": {
      "op": "videos",
      "subject": "example"
    },
    "estimateOnly": false
  }),
});
const envelope = await res.json();
console.log(envelope.data, envelope.cost.creditsCharged);
```

```python
import os, httpx

res = httpx.post(
    "https://api.zomler.com/api/v1/platforms/youtube",
    headers={"X-API-Key": os.environ["ZOMLER_API_KEY"]},
    json={
      "request": {
        "op": "videos",
        "subject": "example"
      },
      "estimateOnly": False
    },
    timeout=120,
)
envelope = res.json()
print(envelope["data"], envelope["cost"]["creditsCharged"])
```

## comments

from 13 credits for 25 · fresh for 1 day

Top comments on up to ten VIDEOS, by watch/shorts URL or bare video id. Commenters are free text — not corpus members.

### Request fields

| Field | Type | Default | Values / limits |
| --- | --- | --- | --- |
| `subjects` (required) | list of string | — | 1-10 items |
| `limit` | integer | `25` | 1-100 |

### Example

```bash
curl -X POST https://api.zomler.com/api/v1/platforms/youtube \
  -H "X-API-Key: zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "op": "comments",
    "subjects": [
      "example"
    ]
  },
  "estimateOnly": false
}'
```

```js
const res = await fetch("https://api.zomler.com/api/v1/platforms/youtube", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ZOMLER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "request": {
      "op": "comments",
      "subjects": [
        "example"
      ]
    },
    "estimateOnly": false
  }),
});
const envelope = await res.json();
console.log(envelope.data, envelope.cost.creditsCharged);
```

```python
import os, httpx

res = httpx.post(
    "https://api.zomler.com/api/v1/platforms/youtube",
    headers={"X-API-Key": os.environ["ZOMLER_API_KEY"]},
    json={
      "request": {
        "op": "comments",
        "subjects": [
          "example"
        ]
      },
      "estimateOnly": False
    },
    timeout=120,
)
envelope = res.json()
print(envelope["data"], envelope["cost"]["creditsCharged"])
```

## history

free · reads what is held

The stored time series — free, reads only what captures already wrote.

### Request fields

| Field | Type | Default | Values / limits |
| --- | --- | --- | --- |
| `subjects` (required) | list of string | — | 1-10 items |
| `metric` | enum | `subscribers` | `subscribers`, `total_videos`, `total_views` |
| `days` | integer | `90` | 1-730 |

### Example

```bash
curl -X POST https://api.zomler.com/api/v1/platforms/youtube \
  -H "X-API-Key: zk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "op": "history",
    "subjects": [
      "example"
    ]
  },
  "estimateOnly": false
}'
```

```js
const res = await fetch("https://api.zomler.com/api/v1/platforms/youtube", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ZOMLER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "request": {
      "op": "history",
      "subjects": [
        "example"
      ]
    },
    "estimateOnly": false
  }),
});
const envelope = await res.json();
console.log(envelope.data, envelope.cost.creditsCharged);
```

```python
import os, httpx

res = httpx.post(
    "https://api.zomler.com/api/v1/platforms/youtube",
    headers={"X-API-Key": os.environ["ZOMLER_API_KEY"]},
    json={
      "request": {
        "op": "history",
        "subjects": [
          "example"
        ]
      },
      "estimateOnly": False
    },
    timeout=120,
)
envelope = res.json()
print(envelope["data"], envelope["cost"]["creditsCharged"])
```

---

Source: https://zomler.com/docs/api/platforms/youtube