{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Transcript API",
    "description": "YouTube transcripts with timestamps and full video metadata from videos, Shorts, playlists, channels and search. Language choice, auto vs human captions flagged, SRT/VTT/text, incremental channel monitoring. Pay only for delivered transcripts.",
    "version": "1.0",
    "x-build-id": "2bVxX1Pz8wHZhPwbH"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/catalyst-labs~youtube-transcript-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-catalyst-labs-youtube-transcript-api",
        "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/catalyst-labs~youtube-transcript-api/runs": {
      "post": {
        "operationId": "runs-sync-catalyst-labs-youtube-transcript-api",
        "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/catalyst-labs~youtube-transcript-api/run-sync": {
      "post": {
        "operationId": "run-sync-catalyst-labs-youtube-transcript-api",
        "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": "YouTube videos, Shorts, playlists or channels",
            "type": "array",
            "description": "One per line: video, Shorts or youtu.be links, 11-character video IDs, playlist URLs, or channel URLs/@handles (add /shorts or /streams for those tabs). Channels return newest videos first.",
            "items": {
              "type": "string"
            }
          },
          "searchQueries": {
            "title": "YouTube search terms",
            "type": "array",
            "description": "Optional. Each term is searched on YouTube and its top videos are transcribed (up to \"Max videos per source\").",
            "items": {
              "type": "string"
            }
          },
          "searchSort": {
            "title": "Search sort",
            "enum": [
              "relevance",
              "date",
              "views",
              "shorts"
            ],
            "type": "string",
            "description": "How search results are ordered.",
            "default": "relevance"
          },
          "maxVideosPerSource": {
            "title": "Max videos per source",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Cap per playlist, channel tab or search term (newest first for channels). 0 = all. Single video links are always included.",
            "default": 50
          },
          "maxVideos": {
            "title": "Max videos in total",
            "minimum": 0,
            "type": "integer",
            "description": "Overall cap across all sources. 0 = no cap.",
            "default": 0
          },
          "publishedAfter": {
            "title": "Published on or after",
            "type": "string",
            "description": "Only videos published on/after this date: YYYY-MM-DD or relative like \"30 days\". Uses exact upload dates."
          },
          "publishedBefore": {
            "title": "Published on or before",
            "type": "string",
            "description": "Only videos published on/before this date: YYYY-MM-DD or relative like \"7 days\"."
          },
          "onlyNewVideos": {
            "title": "Only new videos (incremental monitoring)",
            "type": "boolean",
            "description": "Skip videos this monitor already delivered in earlier runs (not charged). Schedule the run daily to track competitor channels.",
            "default": false
          },
          "monitorId": {
            "title": "Monitor name",
            "type": "string",
            "description": "Optional name for the incremental-monitoring memory, e.g. \"competitors-tech\". Defaults to the list of sources."
          },
          "languages": {
            "title": "Preferred languages",
            "type": "array",
            "description": "Caption languages in order of preference (ISO codes, e.g. en, es, pt-BR). The first one available is returned. Regional variants count: \"en\" also matches en-GB and en-US, and a human-made track in any variant is used before an auto-generated one.",
            "default": [
              "en"
            ],
            "items": {
              "type": "string"
            }
          },
          "captionType": {
            "title": "Caption type",
            "enum": [
              "any",
              "manual",
              "auto"
            ],
            "type": "string",
            "description": "Which caption tracks may be used. Every result says whether it is auto-generated.",
            "default": "any"
          },
          "preferManual": {
            "title": "Prefer human-made captions",
            "type": "boolean",
            "description": "When both exist in a language (including regional variants such as en-GB / en-US), use the human-made track.",
            "default": true
          },
          "translateTo": {
            "title": "Translate to (YouTube auto-translate)",
            "type": "string",
            "description": "Optional ISO code, best effort. If none of the preferred languages exists, ask YouTube for its machine translation. YouTube often refuses these requests from servers; then the original captions are returned with a warning (or TRANSLATION_UNAVAILABLE if fallback is off). Never charged when it fails."
          },
          "fallbackToAnyLanguage": {
            "title": "Fall back to the video's original language",
            "type": "boolean",
            "description": "If no preferred language (or translation) exists, return the video's original spoken language (human-made track if there is one), or the best available track, instead of failing. The result then has requestedLanguageFound=false, languageFallback (\"originalLanguage\" or \"anyLanguage\") and a warning.",
            "default": true
          },
          "outputFormats": {
            "title": "Transcript formats",
            "type": "array",
            "description": "One or more formats per transcript. All formats cost the same. \"LLM-ready text\" adds llmText: the same words with sound cues ([Music], [Applause], (laughs)), music notes and >> speaker markers removed; the raw text field is unchanged.",
            "items": {
              "type": "string",
              "enum": [
                "text",
                "llm",
                "segments",
                "srt",
                "vtt"
              ],
              "enumTitles": [
                "Plain text (paragraphs, exactly as captioned)",
                "LLM-ready text (no [Music], ♪, >> markers)",
                "Timestamped segments",
                "SRT subtitles",
                "WebVTT subtitles"
              ]
            },
            "default": [
              "text",
              "segments"
            ]
          },
          "punctuate": {
            "title": "Restore punctuation on unpunctuated auto-captions",
            "type": "boolean",
            "description": "Some YouTube auto-generated captions come as one long lowercase stream with no punctuation. When enabled, those tracks get sentence punctuation (. , ?) and capitalization restored by a built-in model, returned as punctuatedText (and punctuatedSegments). The raw text and segments are never changed. Human-made captions and auto-captions YouTube already punctuated are left as they are. No extra charge. Supported: English and 44 other space-separated languages (not Japanese/Chinese).",
            "default": false
          },
          "includeMetadata": {
            "title": "Video metadata",
            "type": "boolean",
            "description": "Title, channel, duration, views, tags, thumbnail.",
            "default": true
          },
          "includeDetails": {
            "title": "Publish date, likes, comments and subscribers",
            "type": "boolean",
            "description": "Adds publishDate, likeCount, commentCount and the channel's subscriberCount (one extra request per video, no extra charge). YouTube rounds comment counts above 1,000 and subscriber counts (e.g. 2.4M), so those are approximate. Turned on automatically when you use a date filter.",
            "default": true
          },
          "includeDescription": {
            "title": "Video description",
            "type": "boolean",
            "description": "Adds the full video description.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Leave empty for automatic mode: the Actor starts without a proxy and, if YouTube blocks it, switches to Apify datacenter and then residential proxy at no extra cost to you. Set your own proxy here to override."
          },
          "disableAutoProxy": {
            "title": "Disable automatic proxy escalation",
            "type": "boolean",
            "description": "Only for debugging: never switch to a proxy automatically.",
            "default": false
          },
          "maxConcurrency": {
            "title": "Parallel requests",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Videos fetched in parallel.",
            "default": 5
          },
          "maxRetries": {
            "title": "Retries per request",
            "minimum": 0,
            "maximum": 6,
            "type": "integer",
            "description": "Retries with backoff (and a fresh proxy session) after rate limits or network errors.",
            "default": 3
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}