{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Transcript Scraper & API - Transcripts + Comments",
    "description": "YouTube transcript API and scraper: get transcripts, captions and subtitles in the language you choose from videos, channels, playlists or search, plus top comments. Timestamped segments, text or markdown chunks for AI, RAG, n8n and MCP. No-caption videos are free. $0.80 per 1,000 transcripts.",
    "version": "0.2",
    "x-build-id": "myod6ea7G6wHuEeWO"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/superxcoder~youtube-transcripts-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-superxcoder-youtube-transcripts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/superxcoder~youtube-transcripts-scraper/runs": {
      "post": {
        "operationId": "runs-sync-superxcoder-youtube-transcripts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/superxcoder~youtube-transcripts-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-superxcoder-youtube-transcripts-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "videos": {
            "title": "Video links",
            "type": "array",
            "description": "Paste YouTube video links, one per line. Example: https://www.youtube.com/watch?v=dQw4w9WgXcQ. Share links (youtu.be/...), Shorts and live links work too. The example video is filled in so you can try the Actor at once: remove it if you only want channels, playlists or searches, or you also get (and pay for) its transcript.",
            "items": {
              "type": "string"
            }
          },
          "channels": {
            "title": "Channels",
            "type": "array",
            "description": "Get the newest videos of a channel. Easiest: open the channel on YouTube and copy the address from your browser, e.g. https://www.youtube.com/@mkbhd. A handle like @mkbhd also works, but it must be spelled exactly as on YouTube.",
            "items": {
              "type": "string"
            }
          },
          "maxVideosPerChannel": {
            "title": "Videos per channel",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "How many of the newest videos to take from each channel. Example: 50 for a channel's last 50 videos.",
            "default": 10
          },
          "playlists": {
            "title": "Playlists",
            "type": "array",
            "description": "Paste playlist links, one per line. Example: https://www.youtube.com/playlist?list=PL... (open the playlist on YouTube and copy the address). Videos are taken in playlist order.",
            "items": {
              "type": "string"
            }
          },
          "maxVideosPerPlaylist": {
            "title": "Videos per playlist",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "How many videos to take from each playlist, from the top. Example: 5 for the first 5 lectures.",
            "default": 50
          },
          "searchQueries": {
            "title": "Search words",
            "type": "array",
            "description": "Search YouTube and get transcripts of the top videos. One search per line. Example: langchain tutorial. Only regular videos are returned (no channels, playlists or ads).",
            "items": {
              "type": "string"
            }
          },
          "maxResultsPerSearch": {
            "title": "Videos per search",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "How many videos to take from each search, in YouTube's order. Example: 10.",
            "default": 10
          },
          "languages": {
            "title": "Transcript languages",
            "type": "array",
            "description": "Two-letter language codes, best first, one per line. Examples: en = English, es = Spanish, hi = Hindi, de = German, pt-BR = Portuguese (Brazil). \"en\" also matches US and UK English. Human-made captions are used before automatic ones. Translation is not offered, because YouTube blocks translated captions.",
            "default": [
              "en"
            ],
            "items": {
              "type": "string"
            }
          },
          "outputFormat": {
            "title": "Transcript format",
            "enum": [
              "text",
              "markdown",
              "both",
              "segments"
            ],
            "type": "string",
            "description": "Plain text gives one transcript cell per video. Markdown splits each transcript into sections, each with a [mm:ss] time heading and a link to that moment in the video (see the Markdown tab). Timestamped lines give every caption line with its start time and length in seconds.",
            "default": "text"
          },
          "includeTimestamps": {
            "title": "Timestamps in plain text",
            "type": "boolean",
            "description": "Start each caption line of the plain text with its time, like \"[01:23] text\", one line per caption. Only for the plain-text formats. Off: the plain text is one paragraph.",
            "default": false
          },
          "includeMetadata": {
            "title": "Extra video details",
            "type": "boolean",
            "description": "Also get the exact publish time, like count, category and channel @handle. Title, channel, duration, views, description, keywords and thumbnail always come with the video. Turn off for slightly faster runs when you only need the text.",
            "default": true
          },
          "includeComments": {
            "title": "Include comments",
            "type": "boolean",
            "description": "Also get the top comments of each video that has a transcript. Each comment costs extra (see Pricing). Videos without a transcript get no comments and cost nothing.",
            "default": false
          },
          "maxCommentsPerVideo": {
            "title": "Comments per video",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "How many comments to get per video (replies are not included). Example: 5. The creator's own pinned comment, often a promo link, is usually the first one and counts towards this number.",
            "default": 20
          },
          "channelTab": {
            "title": "Channel tab",
            "enum": [
              "videos",
              "shorts",
              "streams"
            ],
            "type": "string",
            "description": "Which list of a channel to read. Example: Shorts to get a channel's latest Shorts.",
            "default": "videos"
          },
          "searchSort": {
            "title": "Search order",
            "enum": [
              "relevance",
              "popularity"
            ],
            "type": "string",
            "description": "Order of search results. YouTube no longer offers \"newest first\" for search; use \"Uploaded within\" for recent videos.",
            "default": "relevance"
          },
          "searchUploadDate": {
            "title": "Uploaded within",
            "enum": [
              "",
              "hour",
              "today",
              "week",
              "month",
              "year"
            ],
            "type": "string",
            "description": "Only search results uploaded within this period. Example: This month.",
            "default": ""
          },
          "languageFallback": {
            "title": "If a video is not in your languages",
            "enum": [
              "original",
              "any",
              "none"
            ],
            "type": "string",
            "description": "With the first two options you may get a transcript in a different language than you asked for (e.g. Bengali when you asked for Hindi), and it is charged like any transcript. \"Spoken language\" uses YouTube's automatic captions to tell the spoken language; when a video has none, the first human-made captions are used, which can be any language. The \"Language chosen\" column shows when this happened. Choose \"Skip\" if you only want your languages.",
            "default": "original"
          },
          "includeAutoGenerated": {
            "title": "Allow automatic captions",
            "type": "boolean",
            "description": "Use YouTube's automatic (speech recognition) captions when there are no human-made ones. Most videos only have automatic captions. Turn off to get only human-made captions; other videos then come back as \"no captions\" and are not charged.",
            "default": true
          },
          "skipVideosWithoutCaptions": {
            "title": "Leave out videos without captions",
            "type": "boolean",
            "description": "Do not add rows for videos that have no usable captions. These videos are never charged either way. They still count towards \"Max videos in total\".",
            "default": false
          },
          "commentsSort": {
            "title": "Comment order",
            "enum": [
              "top",
              "newest"
            ],
            "type": "string",
            "description": "Which comments to take first. Example: Newest first.",
            "default": "top"
          },
          "chunkCharacters": {
            "title": "Markdown section size (characters)",
            "minimum": 200,
            "maximum": 20000,
            "type": "integer",
            "description": "Rough length of each Markdown section. Only used with the Markdown format. Example: 1500 (about a page of text, or 2 minutes of speech).",
            "default": 1500
          },
          "maxItems": {
            "title": "Max videos in total",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Safety limit: stop after this many videos across all inputs. Example: 100. Videos without captions count too. To cap what you pay, set \"Maximum cost per run\" in Run options, next to the Start button. (Older tasks that use \"maxVideos\" still work.)",
            "default": 1000
          },
          "maxConcurrency": {
            "title": "Parallel videos",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "No need to change. How many videos to fetch at the same time. Example: 10. Higher numbers are rarely faster.",
            "default": 10
          },
          "videoTimeoutSecs": {
            "title": "Time limit per video (seconds)",
            "minimum": 20,
            "maximum": 900,
            "type": "integer",
            "description": "No need to change. Longest time one attempt at one video may take before it is retried. Each web request inside it is limited to a third of this (at most 30 s). Comment fetching gets extra time on top. Example: 120.",
            "default": 120
          },
          "maxRetries": {
            "title": "Retries per video",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "No need to change. How many times a video (or a channel, playlist or search page) is tried again after a rate limit (HTTP 429), timeout or network error, after a short, growing pause. A bot check is not retried. Videos that still fail get a row with status \"error\" and are not charged. Example: 6.",
            "default": 6
          },
          "proxyConfiguration": {
            "title": "Proxy (connection)",
            "type": "object",
            "description": "Leave as is. The default (Apify residential proxy) is included in the price, so it costs you nothing extra. Changing it can make YouTube block the captions. Pick a country to get the videos available there; with no country, a region-limited video can come back GEO_RESTRICTED (free).",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}