transcriptapi-com YouTube video API

openapi: 3.2.0
info:
  title: YouTube Transcript API - Public YouTube video 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 video
  description: 'Get a video''s stats and context without transcribing: view and like counts, publish date, the full description with its links extracted, and related videos. Add include=details for duration, category, tags, and caption availability.'
paths:
  /api/v2/youtube/video/metadata:
    get:
      tags:
      - YouTube video
      summary: Video metadata (no captions required)
      description: 'Inspect a video''s metadata without needing captions: title, view/like count text, publish date, structured description + links, uploading-channel summary, and thumbnails.


        **Optional `include`** (comma-separated) adds heavier data:

        - `related` — related videos.

        - `details` — duration, category, tags, official thumbnails, caption-track inventory and availability flags. These come from YouTube''s player endpoint, which requires our proxied (production) path; where unavailable, `details.available` is `false` with a `reason` rather than guessed values.


        Display strings and numbers are kept distinct; hidden counts are `null`, never `0`.


        **Freshness:** cached for 5 minutes.


        **Credit cost:** 1 credit per request.'
      operationId: get_video_metadata_api_v2_youtube_video_metadata_get
      security:
      - bearerAuth: []
      parameters:
      - name: video_url
        in: query
        required: true
        schema:
          type: string
          description: YouTube video URL or 11-character video ID
          title: Video Url
        description: YouTube video URL or 11-character video ID
      - name: include
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Comma-separated extras: details, related'
          title: Include
        description: 'Comma-separated extras: details, related'
        examples:
          details_and_related:
            summary: Full detail, plus related videos
            description: Adds duration/category/tags/caption inventory and a related-videos list.
            value: details,related
          related_only:
            summary: Related videos only
            value: related
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__v2__youtube__schemas_youtube__VideoInfoResponse'
        '400':
          description: '**Bad Request** - Missing or invalid parameters. **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
        '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** - The requested resource 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
        '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: '**Unprocessable** - `video_url` is not a valid YouTube video URL or ID.'
          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:
                bad_id:
                  summary: Invalid video reference
                  value:
                    detail: Invalid video URL or ID
        '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:
    VideoCaptionTrack:
      properties:
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        isAutoGenerated:
          type: boolean
          title: Isautogenerated
          default: false
      type: object
      title: VideoCaptionTrack
    DescriptionLink:
      properties:
        text:
          anyOf:
          - type: string
          - type: 'null'
          title: Text
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
      type: object
      title: DescriptionLink
    VideoInfoChannel:
      properties:
        channelId:
          anyOf:
          - type: string
          - type: 'null'
          title: Channelid
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        subscriberCountText:
          anyOf:
          - type: string
          - type: 'null'
          title: Subscribercounttext
        thumbnails:
          items:
            $ref: '#/components/schemas/Thumbnail'
          type: array
          title: Thumbnails
      type: object
      title: VideoInfoChannel
    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
    RelatedVideo:
      properties:
        kind:
          type: string
          title: Kind
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        viewCountText:
          anyOf:
          - type: string
          - type: 'null'
          title: Viewcounttext
        lengthText:
          anyOf:
          - type: string
          - type: 'null'
          title: Lengthtext
        channelName:
          anyOf:
          - type: string
          - type: 'null'
          title: Channelname
      type: object
      required:
      - kind
      title: RelatedVideo
    VideoInfoDetails:
      properties:
        available:
          type: boolean
          title: Available
          default: false
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        lengthSeconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Lengthseconds
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
        isLiveContent:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Islivecontent
        isFamilySafe:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Isfamilysafe
        isUnlisted:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Isunlisted
        allowRatings:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allowratings
        thumbnails:
          items:
            $ref: '#/components/schemas/Thumbnail'
          type: array
          title: Thumbnails
        captionTracks:
          items:
            $ref: '#/components/schemas/VideoCaptionTrack'
          type: array
          title: Captiontracks
      type: object
      title: VideoInfoDetails
      description: 'Player-sourced details. `available` is False (with `reason`) when the

        player endpoint could not be read from the current IP (needs a residential

        proxy — production). Numeric-vs-display values are kept distinct.'
    app__api__v2__youtube__schemas_youtube__VideoInfoResponse:
      properties:
        videoId:
          anyOf:
          - type: string
          - type: 'null'
          title: Videoid
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        viewCountText:
          anyOf:
          - type: string
          - type: 'null'
          title: Viewcounttext
        viewCountShort:
          anyOf:
          - type: string
          - type: 'null'
          title: Viewcountshort
        publishDate:
          anyOf:
          - type: string
          - type: 'null'
          title: Publishdate
        relativeDate:
          anyOf:
          - type: string
          - type: 'null'
          title: Relativedate
        likeCountText:
          anyOf:
          - type: string
          - type: 'null'
          title: Likecounttext
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        descriptionLinks:
          items:
            $ref: '#/components/schemas/DescriptionLink'
          type: array
          title: Descriptionlinks
        channel:
          anyOf:
          - $ref: '#/components/schemas/VideoInfoChannel'
          - type: 'null'
        thumbnails:
          items:
            $ref: '#/components/schemas/Thumbnail'
          type: array
          title: Thumbnails
        details:
          anyOf:
          - $ref: '#/components/schemas/VideoInfoDetails'
          - type: 'null'
        related:
          anyOf:
          - items:
              $ref: '#/components/schemas/RelatedVideo'
            type: array
          - type: 'null'
          title: Related
      type: object
      title: VideoInfoResponse
    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