transcriptapi-com YouTube playlist API

openapi: 3.2.0
info:
  title: YouTube Transcript API - Public YouTube playlist API
  description: 'TranscriptAPI: extract the transcript of any YouTube video as structured JSON, with or without timestamps. The same API also covers search, channels, playlists, and video metadata.


    Base URL: https://transcriptapi.com (every path below is under /api/v2/youtube).


    Auth: send Authorization: Bearer YOUR_API_KEY. Get a key at https://transcriptapi.com/dashboard/api-keys.


    Credits: failed calls and 429s cost 0; successful calls cost 1 credit unless the endpoint states otherwise. Costs are stated on each endpoint, including per-page pricing on paginated endpoints. Cached responses (HTTP 200) also cost 1 credit.


    Rate limits: 200 requests per minute per key. Honor X-RateLimit headers and Retry-After on 429.


    Errors: every endpoint documents its status codes and retry flags; retry only 408, 429, and 503.


    Common tasks:

    - Transcribe a video: GET /api/v2/youtube/transcript?video_url=UF8uR6Z6KLc

    - Find videos on a topic to transcribe: GET /api/v2/youtube/search?q=ocean+conservation&type=video&upload_date=week

    - Size up a channel (subscribers, video count, tabs): GET /api/v2/youtube/channel/info?channel=@NASA

    - Pull a channel''s videos, Shorts, or streams: GET /api/v2/youtube/channel/videos?channel=@NASA&tab=shorts

    - Get a video''s likes, views, description links, and related videos: GET /api/v2/youtube/video/metadata?video_url=UF8uR6Z6KLc&include=related

    - List a playlist''s videos: GET /api/v2/youtube/playlist/videos?playlist=

    - Check a video''s available transcript languages, at no credit cost: GET /api/v2/youtube/info?video_url=UF8uR6Z6KLc

    - Do all of this from Claude Desktop or any MCP client: https://transcriptapi.com/docs/mcp


    Guides and full reference: https://transcriptapi.com/docs/api'
  version: 1.0.0
servers:
- url: https://transcriptapi.com
security:
- bearerAuth: []
tags:
- name: YouTube playlist
  description: 'Walk every video in a playlist, paginated: a full course, season, or collection, ready to process.'
paths:
  /api/v2/youtube/playlist/videos:
    get:
      tags:
      - YouTube playlist
      summary: Paginated playlist videos
      description: 'List videos in a playlist (paginated, ~100 per page).


        First request: provide `playlist` (YouTube playlist URL or playlist ID). Subsequent requests: provide `continuation` token.


        **Credit cost:** 1 credit per page.'
      operationId: playlist_videos_api_v2_youtube_playlist_videos_get
      security:
      - bearerAuth: []
      parameters:
      - name: playlist
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Playlist identifier: YouTube playlist URL or playlist ID (PL..., UU..., etc.)'
          title: Playlist
        description: 'Playlist identifier: YouTube playlist URL or playlist ID (PL..., UU..., etc.)'
        examples:
          playlist_id:
            summary: By playlist ID
            value: PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI
      - name: continuation
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          description: Continuation token from previous page
          title: Continuation
        description: Continuation token from previous page
        examples:
          next_page:
            summary: Fetch the next page
            description: Opaque token copied verbatim from the previous response's `continuation` field.
            value: <continuation-token-from-previous-response>
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistVideosResponse'
        '400':
          description: '**Bad Request** - Invalid parameter combination. Provide either `playlist` or `continuation`, not both.'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
              examples:
                missing:
                  summary: No parameter provided
                  value:
                    detail: Either 'playlist' or 'continuation' is required
                both:
                  summary: Both parameters provided
                  value:
                    detail: Provide either 'playlist'/'playlist_id' or 'continuation', not both
        '401':
          description: Unauthorized - invalid Authorization format or API key
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
          headers:
            WWW-Authenticate:
              description: Authentication scheme for this endpoint
              schema:
                type: string
                example: Bearer
        '402':
          description: Payment Required - inactive plan or exhausted credits
          content:
            application/json:
              schema:
                $defs:
                  PaymentActionDetail:
                    properties:
                      message:
                        description: User-friendly explanation of why payment is required
                        title: Message
                        type: string
                      reason:
                        description: Machine-readable reason for the payment requirement
                        enum:
                        - insufficient_credits
                        - no_active_paid_plan
                        title: Reason
                        type: string
                      action_label:
                        description: Short label for the recommended action CTA
                        title: Action Label
                        type: string
                      action_url:
                        description: URL to take the recommended action (top-up or pricing)
                        title: Action Url
                        type: string
                    required:
                    - message
                    - reason
                    - action_label
                    - action_url
                    title: PaymentActionDetail
                    type: object
                properties:
                  detail:
                    $ref: '#/components/schemas/PaymentActionDetail'
                required:
                - detail
                title: PaymentRequiredResponse
                type: object
              examples:
                topup:
                  summary: Active paid plan but credits exhausted
                  value:
                    detail:
                      message: You have an active plan, but you've run out of credits.
                      reason: insufficient_credits
                      action_label: Top up credits
                      action_url: https://transcriptapi.com/top-up
                billing:
                  summary: No active paid plan
                  value:
                    detail:
                      message: You don't have an active paid plan yet.
                      reason: no_active_paid_plan
                      action_label: Go to billing to choose a plan
                      action_url: https://transcriptapi.com/billing
        '404':
          description: '**Not Found** - Playlist does not exist. **Do not retry.**'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
              examples:
                not_found:
                  summary: Playlist not found
                  value:
                    detail: Playlist not found
        '408':
          description: '**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
              examples:
                retry:
                  summary: Temporary failure - retry recommended
                  value:
                    detail: Request failed, please retry
        '422':
          description: '**Validation Error** - Invalid playlist identifier. Must be a playlist URL or ID starting with `PL`, `UU`, `LL`, `FL`, or `OL`. **Do not retry** with the same input.'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
              examples:
                invalid_playlist_id:
                  summary: Invalid playlist identifier
                  value:
                    detail: Invalid playlist identifier
        '429':
          description: '**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.'
          headers:
            Retry-After:
              description: Seconds until the limit resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
        '500':
          description: '**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
              examples:
                server_error:
                  summary: Unexpected server error
                  value:
                    detail: Internal server error
        '503':
          description: '**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    description: Human-readable error message
                    title: Detail
                    type: string
                  code:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Optional machine-readable error code
                    title: Code
                required:
                - detail
                title: ErrorResponse
                type: object
              examples:
                unavailable:
                  summary: Service temporarily unavailable
                  value:
                    detail: Service not initialized
components:
  schemas:
    PlaylistVideoResult:
      properties:
        videoId:
          anyOf:
          - type: string
          - type: 'null'
          title: Videoid
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        channelId:
          anyOf:
          - type: string
          - type: 'null'
          title: Channelid
        channelTitle:
          anyOf:
          - type: string
          - type: 'null'
          title: Channeltitle
        channelHandle:
          anyOf:
          - type: string
          - type: 'null'
          title: Channelhandle
        lengthText:
          anyOf:
          - type: string
          - type: 'null'
          title: Lengthtext
        viewCountText:
          anyOf:
          - type: string
          - type: 'null'
          title: Viewcounttext
        publishedTimeText:
          anyOf:
          - type: string
          - type: 'null'
          title: Publishedtimetext
        thumbnails:
          items:
            $ref: '#/components/schemas/Thumbnail'
          type: array
          title: Thumbnails
        index:
          anyOf:
          - type: string
          - type: 'null'
          title: Index
        members_only:
          type: boolean
          title: Members Only
          description: Video is behind a channel membership (YouTube's "Members only" badge). Always `false` on the uploads feed and on playlists, which never include membership content. Members-only items have no `viewCountText` — YouTube does not publish view counts for them.
          default: false
      type: object
      title: PlaylistVideoResult
    Thumbnail:
      properties:
        url:
          type: string
          title: Url
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
      type: object
      required:
      - url
      title: Thumbnail
    PlaylistInfo:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        numVideos:
          anyOf:
          - type: string
          - type: 'null'
          title: Numvideos
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        ownerName:
          anyOf:
          - type: string
          - type: 'null'
          title: Ownername
        viewCount:
          anyOf:
          - type: string
          - type: 'null'
          title: Viewcount
      type: object
      title: PlaylistInfo
    PlaylistVideosResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/PlaylistVideoResult'
          type: array
          title: Results
        playlist_info:
          anyOf:
          - $ref: '#/components/schemas/PlaylistInfo'
          - type: 'null'
        continuation_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Continuation Token
        has_more:
          type: boolean
          title: Has More
          default: false
      type: object
      title: PlaylistVideosResponse
    PaymentActionDetail:
      properties:
        message:
          description: User-friendly explanation of why payment is required
          title: Message
          type: string
        reason:
          description: Machine-readable reason for the payment requirement
          enum:
          - insufficient_credits
          - no_active_paid_plan
          title: Reason
          type: string
        action_label:
          description: Short label for the recommended action CTA
          title: Action Label
          type: string
        action_url:
          description: URL to take the recommended action (top-up or pricing)
          title: Action Url
          type: string
      required:
      - message
      - reason
      - action_label
      - action_url
      title: PaymentActionDetail
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: 'Use Authorization: Bearer {your_api_key}'
      scheme: bearer