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

# Download Video Subtitles

> Streams the specified YouTube video's subtitle data as a JSON file download with the filename format `{videoId}-{vssId}.json`. Returns a `content-disposition` attachment. Returns `404` if the video or subtitle ID is not found.



## OpenAPI

````yaml /api-v3/api-v3.yaml get /youtube/subtitles/download
openapi: 3.1.0
info:
  version: 1.0.0
  title: CreatorDB Headless API V3
  description: '# CreatorDB Headless API V3'
  contact:
    name: CreatorDB
    url: https://www.creatordb.app
    email: support@creatordb.app
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
servers:
  - url: https://apiv3.creatordb.app
    description: Production Environment (CreatorDB Headless API V3)
security:
  - ApiKeyAuth: []
tags:
  - name: Brand
    description: Brand analysis endpoints including sponsor search and brand reports.
  - name: Facebook
    description: Facebook creator data endpoints with metrics and search capabilities.
  - name: General Operations
    description: >-
      General-purpose endpoints such as API status, content retrieval, and
      cross-platform operations.
  - name: Instagram
    description: >-
      Instagram creator data endpoints with metrics and advanced search
      capabilities.
  - name: Niches
    description: >-
      Niche-related endpoints for content category analysis and related
      searches.
  - name: Threads
    description: Threads creator data endpoints with basic metrics and historical data.
  - name: TikTok
    description: >-
      TikTok creator data endpoints with metrics and advanced search
      functionality.
  - name: Topic
    description: Topic-based analysis and reporting endpoints for content categorization.
  - name: YouTube
    description: >-
      YouTube creator data endpoints including basic metrics, historical data,
      and detailed analytics.
paths:
  /youtube/subtitles/download:
    get:
      tags:
        - YouTube
      summary: Download Video Subtitles
      description: >-
        Streams the specified YouTube video's subtitle data as a JSON file
        download with the filename format `{videoId}-{vssId}.json`. Returns a
        `content-disposition` attachment. Returns `404` if the video or subtitle
        ID is not found.
      operationId: getYoutubeSubtitleDownload
      parameters:
        - name: videoId
          in: query
          description: 'The unique YouTube video ID (length: 11 characters).'
          required: true
          schema:
            type: string
            minLength: 11
            maxLength: 11
            pattern: ^[a-zA-Z0-9_-]{11}$
            examples:
              - icxrUIGoEg8
        - name: vssId
          in: query
          description: >-
            The subtitle language record code (example: `a.en`, `.en`,
            `.zh-Hant`).
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 20
            examples:
              - .en
      responses:
        '200':
          description: >-
            Subtitle data of the specified YouTube video downloaded
            successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  _streaming:
                    type: boolean
                    enum:
                      - true
                description: >-
                  Streams subtitle data as a JSON file download (chunked
                  transfer encoding). Content-Type: application/json,
                  Content-Disposition: attachment;
                  filename="{videoId}-{vssId}.json"
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                type: object
                title: ValidationErrorResponse
                description: Parameter validation error response format.
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: string
                  message:
                    type: string
                  timestamp:
                    type: integer
                required:
                  - success
                  - error
                  - message
                  - timestamp
              examples:
                missing videoId:
                  summary: Missing videoId
                  value:
                    success: false
                    error: VALIDATION_ERROR
                    message: 'Missing required field: ''videoId''.'
                    timestamp: 1770099403116
                missing vssId:
                  summary: Missing vssId
                  value:
                    success: false
                    error: VALIDATION_ERROR
                    message: 'Missing required field: ''vssId''.'
                    timestamp: 1770099403116
        '429':
          description: Exceeded quota or rate limit.
          content:
            application/json:
              schema:
                type: object
                title: QuotaErrorResponse
                description: Quota error response format.
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: string
                  message:
                    type: string
                  remainingPlanCredit:
                    type: number
                required:
                  - success
                  - error
                  - message
                  - remainingPlanCredit
              examples:
                rate limit:
                  summary: Rate limit exceeded
                  value:
                    success: false
                    error: RATE_LIMIT_EXCEEDED
                    message: Too many requests. Please try again later.
                quota exceeded:
                  summary: Credit quota exceeded
                  value:
                    success: false
                    error: QUOTA_EXCEEDED
                    message: Not enough credits to complete this request.
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >
            curl -X GET
            "https://apiv3.creatordb.app/youtube/subtitles/download?videoId=icxrUIGoEg8&vssId=.en"
            \
              -H "api-key: <YOUR_API-KEY_HERE>"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: The valid CreatorDB API key for authentication.
      name: api-key
      in: header

````