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

# Channel live streams

> Fetches a YouTube channel's live streams (its Live tab), 30 per page, latest first: streams scheduled to start, streams live now and past streams. Each one has its id, URL, title and `status` (`upcoming`, `live` or `ended`), plus what YouTube shows for that state: the scheduled start time and how many are waiting, how many are watching now, or a past stream's views, length and when it aired; and its thumbnail, moving preview and members-only flag. `counts` gives how many of each state are on the page. The response also carries a summary of the channel (id, handle, name, avatar, verified, subscribers). Pass exactly one of `channelId` or `handle`; pass the returned `cursor` back (with the same channel) for the next page. A channel without a Live tab returns no streams. Only publicly available data is returned.

> [!NOTE]
>
> **Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free.

> [accordion] Copy for AI assistant
>
> Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button).
>
> ```text Prompt
> I want to make an API call to /v1/youtube/channel/lives. Here are the details:
>
> Endpoint: GET https://api.scraperize.com/v1/youtube/channel/lives
> Description: Fetches a YouTube channel's live streams (its Live tab), 30 per page, latest first: streams scheduled to start, streams live now and past streams. Each one has its id, URL, title and `status` (`upcoming`, `live` or `ended`), plus what YouTube shows for that state: the scheduled start time and how many are waiting, how many are watching now, or a past stream's views, length and when it aired; and its thumbnail, moving preview and members-only flag. `counts` gives how many of each state are on the page. The response also carries a summary of the channel (id, handle, name, avatar, verified, subscribers). Pass exactly one of `channelId` or `handle`; pass the returned `cursor` back (with the same channel) for the next page. A channel without a Live tab returns no streams. Only publicly available data is returned.
>
> Required Headers:
> - x-api-key: Your API key
>
> Parameters:
> - channelId (string): The channel id: `UC` followed by 22 characters, e.g. `UCLA_DiR1FfKNvjuUpBHmylQ`.
> - handle (string): The channel handle, with or without `@`, e.g. `NASA`.
> - cursor (string): The `cursor` from the previous page, to get the next one. Omit for the first page.
> - cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh.
>
> Example Response:
> {
>   "data": {
>     "channel": {
>       "id": "UCLA_DiR1FfKNvjuUpBHmylQ",
>       "handle": "NASA",
>       "name": "NASA",
>       "url": "https://www.youtube.com/@NASA",
>       "avatarUrl": "https://yt3.googleusercontent.com/eIf5fNPcIcj9ig-wZBeq4stFy1lgjWTW1nLT5dYlFkHZprZ03QBiMcbpwNMB6XSBjrSFGtAGQg=s900-c-k-c0x00ffffff-no-rj",
>       "isVerified": true,
>       "subscriberCount": 15100000
>     },
>     "lives": [
>       {
>         "id": "MRg4uIpJ3xE",
>         "url": "https://www.youtube.com/watch?v=MRg4uIpJ3xE",
>         "title": "NASA Moon Base: November 2026 Update (Nov. 7, 2026)",
>         "status": "upcoming",
>         "viewCount": null,
>         "viewCountText": null,
>         "concurrentViewers": null,
>         "concurrentViewersText": null,
>         "waitingCount": 7,
>         "scheduledStartAt": "2026-11-07T22:00:00.000Z",
>         "publishedText": null,
>         "durationSeconds": null,
>         "durationText": null,
>         "isMembersOnly": false,
>         "badges": [],
>         "thumbnailUrl": "https://i.ytimg.com/vi/MRg4uIpJ3xE/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAQg16HINHKPW73q_enLITu8If91w",
>         "thumbnails": [
>           {
>             "url": "https://i.ytimg.com/vi/MRg4uIpJ3xE/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAQg16HINHKPW73q_enLITu8If91w",
>             "width": 720,
>             "height": 404
>           }
>         ],
>         "previewUrl": null
>       }
>     ],
>     "counts": {
>       "live": 2,
>       "upcoming": 2,
>       "ended": 26
>     },
>     "count": 30,
>     "cursor": "eyJrIjoiQG5hc2EiLCJjIjoiNHFtRnNnS2hEQklZVlVOTVFWOUVhVkl4Um1aTFRuWnFkVlZ3UWtodGVXeFJHb1FNT0dkaVgwTkNjamhEU0V3MVEwUnlNa05CYjJ0T2JVMDBUbTFHYTAxRVJYUk5SRUYzVFVNd2VV…",
>     "hasMore": true,
>     "fetchedAt": "2026-11-05T06:38:35.443Z"
>   },
>   "meta": {
>     "requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
>     "creditsCharged": 1,
>     "creditsRemaining": 4999,
>     "cached": false
>   }
> }
>
> Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices.
> ```


## OpenAPI

````yaml /api-reference/openapi.json get /v1/youtube/channel/lives
openapi: 3.0.3
info:
  title: Scraperize API
  version: 1.0.0
  description: >-
    Extract public data from social media platforms as clean JSON. Endpoints are
    split by platform and by what they return, e.g. `GET /v1/twitter/tweet`.


    ## Authentication

    Send your API key in the `x-api-key` header (or `Authorization: Bearer
    <key>`). Create keys in your dashboard.


    ## Credits

    Each successful live scrape costs **1 credit**. Credits are prepaid and
    never expire.


    ## Caching

    Every endpoint accepts an optional `cache_max_age`
    (`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for
    **0 credits**.


    ## Responses

    Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return
    `{ "error": { "code", "message", "requestId" } }` with a matching HTTP
    status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`,
    `cached`, and (on a hit) `cachedAt`.


    ## Rate limits

    Requests are limited per team per minute; over the limit returns `429` with
    a `Retry-After` header.
servers:
  - url: https://api.scraperize.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Twitter
    description: Twitter / X scraping endpoints
  - name: Facebook
    description: Facebook scraping endpoints
  - name: Linkme
    description: Linkme (link.me) scraping endpoints
  - name: Amazon
    description: Amazon (creator shop / storefront) scraping endpoints
  - name: Linkbio
    description: Linkbio (lnk.bio) scraping endpoints
  - name: Pillar
    description: Pillar (pillar.io) scraping endpoints
  - name: Komi
    description: Komi (komi.io) scraping endpoints
  - name: Linktree
    description: Linktree (linktr.ee) scraping endpoints
  - name: Kick
    description: Kick (kick.com) scraping endpoints
  - name: Snapchat
    description: Snapchat (snapchat.com) scraping endpoints
  - name: Telegram
    description: Telegram (t.me) scraping endpoints
  - name: LinkedIn
    description: LinkedIn scraping endpoints
  - name: Twitch
    description: Twitch scraping endpoints
  - name: TikTok
    description: TikTok (tiktok.com) scraping endpoints
  - name: Instagram
    description: Instagram scraping endpoints
  - name: Lagos Life
    description: Lagos Life scraping endpoints
  - name: Bluesky
    description: Bluesky (bsky.app) scraping endpoints
  - name: Threads
    description: Threads (threads.com) scraping endpoints
  - name: Reddit
    description: Reddit (reddit.com) scraping endpoints
  - name: Rumble
    description: Rumble (rumble.com) scraping endpoints
  - name: Truth Social
    description: Truth Social (truthsocial.com) scraping endpoints
  - name: YouTube
    description: YouTube (youtube.com) scraping endpoints
paths:
  /v1/youtube/channel/lives:
    get:
      tags:
        - YouTube
      summary: Channel live streams
      description: >-
        Fetches a YouTube channel's live streams (its Live tab), 30 per page,
        latest first: streams scheduled to start, streams live now and past
        streams. Each one has its id, URL, title and `status` (`upcoming`,
        `live` or `ended`), plus what YouTube shows for that state: the
        scheduled start time and how many are waiting, how many are watching
        now, or a past stream's views, length and when it aired; and its
        thumbnail, moving preview and members-only flag. `counts` gives how many
        of each state are on the page. The response also carries a summary of
        the channel (id, handle, name, avatar, verified, subscribers). Pass
        exactly one of `channelId` or `handle`; pass the returned `cursor` back
        (with the same channel) for the next page. A channel without a Live tab
        returns no streams. Only publicly available data is returned.
      parameters:
        - name: channelId
          in: query
          required: false
          description: >-
            The channel id: `UC` followed by 22 characters, e.g.
            `UCLA_DiR1FfKNvjuUpBHmylQ`.
          schema:
            type: string
          example: UCLA_DiR1FfKNvjuUpBHmylQ
        - name: handle
          in: query
          required: false
          description: The channel handle, with or without `@`, e.g. `NASA`.
          schema:
            type: string
          example: NASA
        - name: cursor
          in: query
          required: false
          description: >-
            The `cursor` from the previous page, to get the next one. Omit for
            the first page.
          schema:
            type: string
        - name: cache_max_age
          in: query
          required: false
          description: >-
            Optional. Return a cached result if one this age or newer exists —
            served for **0 credits** with `meta.cached=true` and
            `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and
            refreshes the cache. Omit to always scrape fresh.
          schema:
            type: string
            enum:
              - 1d
              - 3d
              - 7d
              - 14d
              - 30d
          example: 7d
      responses:
        '200':
          description: One page of the channel's live streams (empty when it has none).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      channel:
                        type: object
                      lives:
                        type: array
                        items:
                          type: object
                      counts:
                        type: object
                        properties:
                          live:
                            type: integer
                          upcoming:
                            type: integer
                          ended:
                            type: integer
                      count:
                        type: integer
                      cursor:
                        type: string
                        nullable: true
                      hasMore:
                        type: boolean
                      fetchedAt:
                        type: string
                        format: date-time
                  meta:
                    type: object
                    description: >-
                      requestId + credit/caching metadata (creditsCharged,
                      creditsRemaining, cached, cachedAt).
                required:
                  - data
                  - meta
              example:
                data:
                  channel:
                    id: UCLA_DiR1FfKNvjuUpBHmylQ
                    handle: NASA
                    name: NASA
                    url: https://www.youtube.com/@NASA
                    avatarUrl: >-
                      https://yt3.googleusercontent.com/eIf5fNPcIcj9ig-wZBeq4stFy1lgjWTW1nLT5dYlFkHZprZ03QBiMcbpwNMB6XSBjrSFGtAGQg=s900-c-k-c0x00ffffff-no-rj
                    isVerified: true
                    subscriberCount: 15100000
                  lives:
                    - id: MRg4uIpJ3xE
                      url: https://www.youtube.com/watch?v=MRg4uIpJ3xE
                      title: 'NASA Moon Base: November 2026 Update (Nov. 7, 2026)'
                      status: upcoming
                      viewCount: null
                      viewCountText: null
                      concurrentViewers: null
                      concurrentViewersText: null
                      waitingCount: 7
                      scheduledStartAt: '2026-11-07T22:00:00.000Z'
                      publishedText: null
                      durationSeconds: null
                      durationText: null
                      isMembersOnly: false
                      badges: []
                      thumbnailUrl: >-
                        https://i.ytimg.com/vi/MRg4uIpJ3xE/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAQg16HINHKPW73q_enLITu8If91w
                      thumbnails:
                        - url: >-
                            https://i.ytimg.com/vi/MRg4uIpJ3xE/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAQg16HINHKPW73q_enLITu8If91w
                          width: 720
                          height: 404
                        - url: >-
                            https://i.ytimg.com/vi/MRg4uIpJ3xE/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLCvgcaCNAOQQhWLmzLZDxn85mF0cw
                          width: 360
                          height: 202
                      previewUrl: null
                    - id: 25JEQqgv5I4
                      url: https://www.youtube.com/watch?v=25JEQqgv5I4
                      title: U.S. Spacewalk 101
                      status: upcoming
                      viewCount: null
                      viewCountText: null
                      concurrentViewers: null
                      concurrentViewersText: null
                      waitingCount: 26
                      scheduledStartAt: '2026-11-05T12:00:00.000Z'
                      publishedText: null
                      durationSeconds: null
                      durationText: null
                      isMembersOnly: false
                      badges: []
                      thumbnailUrl: >-
                        https://i.ytimg.com/vi/25JEQqgv5I4/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLASuBqtxRHNDPZbdnXcLtWjwfWYog
                      thumbnails:
                        - url: >-
                            https://i.ytimg.com/vi/25JEQqgv5I4/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLASuBqtxRHNDPZbdnXcLtWjwfWYog
                          width: 720
                          height: 404
                        - url: >-
                            https://i.ytimg.com/vi/25JEQqgv5I4/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLB8u3Vt7IVwYgsHijuiATQlmGJkbA
                          width: 360
                          height: 202
                      previewUrl: null
                    - id: ROboUHfPUrU
                      url: https://www.youtube.com/watch?v=ROboUHfPUrU
                      title: >-
                        Live High-Definition Views from the International Space
                        Station (Official NASA Stream)
                      status: live
                      viewCount: null
                      viewCountText: null
                      concurrentViewers: 92
                      concurrentViewersText: 92 watching
                      waitingCount: null
                      scheduledStartAt: null
                      publishedText: null
                      durationSeconds: null
                      durationText: null
                      isMembersOnly: false
                      badges: []
                      thumbnailUrl: >-
                        https://i.ytimg.com/vi/ROboUHfPUrU/hq720.jpg?v=6ada1dd8&sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBhSVY1KCfQNDXCOy9gDe5kxmDHJA
                      thumbnails:
                        - url: >-
                            https://i.ytimg.com/vi/ROboUHfPUrU/hq720.jpg?v=6ada1dd8&sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLBhSVY1KCfQNDXCOy9gDe5kxmDHJA
                          width: 720
                          height: 404
                        - url: >-
                            https://i.ytimg.com/vi/ROboUHfPUrU/hq720.jpg?v=6ada1dd8&sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLAmapwCC47bPmUvpQ-6q4yJmyaYSw
                          width: 360
                          height: 202
                      previewUrl: null
                  counts:
                    live: 2
                    upcoming: 2
                    ended: 26
                  count: 30
                  cursor: >-
                    eyJrIjoiQG5hc2EiLCJjIjoiNHFtRnNnS2hEQklZVlVOTVFWOUVhVkl4Um1aTFRuWnFkVlZ3UWtodGVXeFJHb1FNT0dkaVgwTkNjamhEU0V3MVEwUnlNa05CYjJ0T2JVMDBUbTFHYTAxRVJYUk5SRUYzVFVNd2VVMUhTWGhNVjBreFdXMU5kRTB5VFhsUFJGcHJUa2RaZWxscVZYbEZjM05KVVZkT1YwOUdXbXRXYldSRFl6Tm9kV1JFUlRWUk1XTXpUa2hHUm1OV1ZqQlpiV3hXVmtWd1RHSXhTa3hWUmtaVVlsZG9NbEpJVWxwTlIxSkhVbXRPYms1VVNuSk5SbFp3V0RCUk1tSnNPVEZOU0VJeVRtNXdiVTlFV2sxa2EwVjZWRE5hYmxGcmMzbGtWVnBYVXpOQ1ZXTXljM2hoTTJ4d1pXdDBhVlJFYkc1Tk0wVjVWak5STVZKclNrOU5WR3hhWkdwQ2JHVnVUbmhhUkZaU1YyMUpNbFJ1Vm5oVlJFNVJXbXhDTVU5SVNuTlNNMlJ2VkVkd1MxZHVWbFJoUlVwd1drUmFSRk5zYUhwU1dFVjNWMWhvUjFZd1JuTmFSVWt5V1RKT1NHSnFTbk5oUm1oeVdESTFhMUY2VG5CUFZGWm9ZM3BzZUZwSE9IZGlTRkl4WldwR1RGZEZiRFJNVnpCM1RVUldORnB1VVhsUFJHUlVUbTFhVG1ReVJuUmhhVEZTV1dwV1MxUXdSWFJoUmtvMFpGWm9kVk51Vm1sT1IzQjNUVmRXYzJJeVRuVmlTRlpQVW5reFdsVXhRbFZqTTA1clVXcEdiazFxVmpCaFdHUnVZMVZXY2xOWFp6VlJla1pTV1ROak1scHROREpPTVVGMFVXa3hUbFF3WjNwTmEwNXRUbGRrVUdOdVJrNU5ia2t5VWxkNGMxSllWbTlOYlVaSlUyczVVbHBYU214YVZXaHRaVVpHV2t4VlpFZGhSRUphVGxWVmVGSkhTbnBhVlZweFl6Sk5lVlp0TVRWV2JXaG1aRmRHTmsxcVRuTmhWMFpFVldwT1IxbHROV2hXVXpGMFdXeEdTMkV5U2xWbFZFcG1VWHBLU0U0eVJsTlRNVGx5VVdwa1RsZHJUbXBhUkUweFlsVndjVkZzVW1GbFZsb3dWVU13TUdOVVdtWk5NalI2VFZWNFFrNUZTbTVOYlRsclYxYzViVTlYVWpaU1IxcE9UVWhrVEU5R1NrWk5hbFpUVVZod1RXSXhXazVWU0VwTVkwUktNR05ZUlROU1ZGcFpXbFk0ZUZoNlVsbFRWM0F4VFZoc2MweFZXazFVYXpWSlRGaE9jRkV5WkhSYVZrcDBWVzB4ZDFnd2VGQlVibFV5VlZSS2NsZFZhREppYkdoU1lqTndWR0ZGTVZGU2EyUktUMVpDVlZGdVVYUmtSa1Y0VjFWS05VMHlWbXhsUjJoWFZrVktSMlZJWkRaWFJrNTBXVlZuZVdOR2JETk5SVGx4VFROa2QyRnNTalJhV0ZwUVpFWldSMkV3Y0ZOVU0wRXhaVmM1TUZkcVpGcFVhVEZ0WXpGd00yRXhiSFZSYldSWFRUSktObFZHYURWYWFsRXlVMnhXWVZGclRqWk9iVFZyVkdwc1RsTnFRWGxUTTBKWVlVWndTMWxyVVhSUmF6VlVVM3BDUzB4Vk5IcFZiRTEwVG0wNGQyUllVbEphV0dONlpXMVZORk5xU1RWbGJWWTBUV3BTUkdNd1VtcFNSR3cyVFZWTk1tTXpjRlpOYTFvMlkxVlJNRnB1YUdaa00zQXpZekU1ZGxSSE1XaFViRTVOVTJ0YVMyTnJWa2hYUXpBMFltdEdUbUl4YURaVlZWWkxUVzVPVUZRd01XcFViRVpoVG0xamQxcHJaRVpVV0ZGNVdtdEtjRkV3YUUxVGJrNVpaV3BhTmxOVk5XMWFWa3BFWVZNeFJGcHJSbE5TU0hBelUyeHdURkZyU25aaE1HaFFXa1Z2TUdOcWJGSlNWbFpTVG01b05GWnRSa05pYTNSU1lVZHdjVlJWVW1wUFdFSXdWMFJrUzFNd01EUlllbEoyVFZaT1ZsUXhiR0ZPVnpsT1ZESjRRMkpWVm5CWGEzUkxXakZHTVZSRVFtRlZNRzkzVGxoc1lVMVljRWRUUmtKM1ZFWmtUMVZWTVZaU1IxSjBWbGMxYUdOck1IcFViVXBvVWpOYVVHTlVUbGhWZVRCNVUydG9TMVpGYUZoVE1EVklXRE5PZG1WdFducFBWVmw0VGtka2JHUnRaSGRoYTBVelVXNWtXRmd6VGtOVFZqbFpVekZDTUZReVRsWllNV3N5WWxkR05GSXdVbHBrVlVwTlpWWmtWMkZGY0V4UFJ6aDNZek5HZWxSWVFUTlVWa1l3VVRCU2NWWlZlRVJVYW1oTVUyMU9kbGx1VWxGYVZrNUZZVWhLTldReVVuTlhWbWhZVkRKb01GUnRPVmxQUkd4WFpHeEdVMUZ0TVRKa2EyUXpWRmMxZW1WdFNqVmFSa0pKVTFWVk1tUnRSa2hQVmxKNVpHNUplbEl5U25oTmJsb3pVVmN4UzJWR1NURlRWR3hMVFcxME1GSXdVVEZqU0ZKMlkwYzFVbVJVVG1aaVJWbzJZVVphYjFsclNUTk9WMFptV25wc1NWVlZVbEpqUjBwdFkxaE9TMlZzT1cxVVdFbzFVMVY0VG1SRk1IcFJNRTV3VW14S1UxRlZSblZXYmxKVFVXcG9ORmxXVmxOVVJHeE5ZbXBXVlZZd2QzbGFiWGcxVGtWV1ZHRXpiRFJNVlZweFQxWkNkRTFETURCUFZWa3lUa0puVFElM0QlM0QiLCJjaCI6eyJpZCI6IlVDTEFfRGlSMUZmS052anVVcEJIbXlsUSIsImhhbmRsZSI6Ik5BU0EiLCJuYW1lIjoiTkFTQSIsInVybCI6Imh0dHBzOi8vd3d3LnlvdXR1YmUuY29tL0BOQVNBIiwiYXZhdGFyVXJsIjoiaHR0cHM6Ly95dDMuZ29vZ2xldXNlcmNvbnRlbnQuY29tL2VJZjVmTlBjSWNqOWlnLXdaQmVxNHN0RnkxbGdqV1RXMW5MVDVkWWxGa0hacHJaMDNRQmlNY2Jwd05NQjZYU0JqclNGR3RBR1FnPXM5MDAtYy1rLWMweDAwZmZmZmZmLW5vLXJqIiwiaXNWZXJpZmllZCI6dHJ1ZSwic3Vic2NyaWJlckNvdW50IjoxNTEwMDAwMH19
                  hasMore: true
                  fetchedAt: '2026-11-05T06:38:35.443Z'
                meta:
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
                  creditsCharged: 1
                  creditsRemaining: 4999
                  cached: false
        '400':
          description: Invalid or expired cursor (or one for another channel).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BAD_REQUEST
                  message: The request was invalid.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '401':
          description: Missing, invalid, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNAUTHORIZED
                  message: API key required — pass it in the `x-api-key` header.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '402':
          description: Not enough credits for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INSUFFICIENT_CREDITS
                  message: >-
                    This request costs 1 credit, but your balance is 0. Top up
                    to continue.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '404':
          description: No YouTube channel found (it may not exist or have been removed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: >-
                    The requested content was not found (it may not exist, be
                    deleted, or be private).
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '422':
          description: Invalid query parameters (pass exactly one of channelId or handle).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
                  details:
                    - path: url
                      message: url is required
        '429':
          description: Over the per-minute rate limit — honour `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: >-
                    Rate limit exceeded — max 100 requests per 60s. Retry in
                    ~30s.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '503':
          description: >-
            Temporarily unavailable — retry after `Retry-After`. `error.code`
            tells you why: `UPSTREAM_BLOCKED` (the source blocked this request),
            `EXTRACTION_FAILED` (the source returned unexpected data),
            `PLATFORM_UNAVAILABLE` (the source is down), or
            `SERVICE_UNAVAILABLE` (we are at capacity).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UPSTREAM_BLOCKED
                  message: >-
                    The source is temporarily unavailable. Please try again
                    shortly.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: The requested content was not found.
            requestId:
              type: string
              example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
            details:
              type: array
              items:
                type: object
              description: Present on validation errors.
          required:
            - code
            - message
            - requestId
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your API key. Send it in the `x-api-key` header (or `Authorization:
        Bearer <key>`). Create and manage keys from your dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.