{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Video Details Scraper: Most Replayed",
    "description": "YouTube Video Details Scraper: Extract video titles, descriptions, channels, views, likes, comments, chapters, timestamps, and most-replayed sections. Analyze viewer interest, engagement patterns, high-retention moments, and content performance for YouTube research and optimization.",
    "version": "0.1",
    "x-build-id": "Esw1n2AZ1GzU92dVC"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/api-empire~youtube-video-details-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-api-empire-youtube-video-details-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/api-empire~youtube-video-details-scraper/runs": {
      "post": {
        "operationId": "runs-sync-api-empire-youtube-video-details-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/api-empire~youtube-video-details-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-api-empire-youtube-video-details-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": {
          "videoUrls": {
            "title": "🎬 Video URLs",
            "type": "array",
            "description": "One or more YouTube **video** URLs. Accepts `https://www.youtube.com/watch?v=ID`, `https://youtu.be/ID` and `/shorts/ID`.\n\nPlaylist and channel URLs are not supported — this Actor returns per-video depth, one row per video.\n\nThe legacy input key `startUrls` is still accepted, so runs and integrations built against the original Actor keep working unchanged.",
            "items": {
              "type": "string"
            }
          },
          "includeHeatmapCurve": {
            "title": "🔥 Return the full replay curve",
            "type": "boolean",
            "description": "Return `heatmap[]` — YouTube's most-replayed graph as 100 buckets of `{startTime, endTime, replayValue, rank}`.\n\nTurn this off if you only want the single peak second (`mostReplayedAt`), which is still returned either way. Default: on.\n\nMeasured availability: 100 buckets on 6 of 6 test videos, including a 1-second Short.",
            "default": true
          },
          "includeChapters": {
            "title": "📑 Return chapter markers",
            "type": "boolean",
            "description": "Return `chapters[]` — `{index, title, startTime, endTime, durationSeconds, url}` for every creator-defined chapter, plus `hasChapters` and `chapterCount`.\n\nOnly ~2 of 3 videos have chapters at all. When a video has none you get `hasChapters: false`, an empty array and `null` chapter titles on the clip windows — never an invented chapter name. Default: on.",
            "default": true
          },
          "maxReplayPeaks": {
            "title": "✂️ Clip windows to return",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "How many replay peaks to turn into clip windows. Each window is `{rank, startTime, endTime, replayValue, chapterTitle, transcriptText, url}`.\n\nPeaks are picked greedily from the highest bucket down and are kept non-overlapping, so you get distinct moments rather than five neighbouring slices of one spike.\n\nExample: `5` on a tutorial returns the five most-rewatched moments with the section name and what is said there. Set `0` to skip clip windows. Default: 5.",
            "default": 5
          },
          "peakWindowThreshold": {
            "title": "📐 Window width sensitivity",
            "minimum": 0.1,
            "maximum": 1,
            "type": "number",
            "description": "How far a clip window grows out from its peak. A window expands while neighbouring buckets stay at or above `peak × threshold`.\n\n`0.9` = tight windows around the exact spike. `0.5` = wide windows covering the whole rewatched stretch. Default: 0.75.",
            "default": 0.75
          },
          "maxClipSeconds": {
            "title": "⏱️ Maximum clip window length (seconds)",
            "minimum": 5,
            "maximum": 3600,
            "type": "integer",
            "description": "Hard cap on how long a single clip window may run. On a 3-hour podcast one heatmap bucket is already ~108 seconds, so raise this for long-form content and lower it for tight highlight cuts. Default: 90.",
            "default": 90
          },
          "includeChapterReplayShare": {
            "title": "📊 Replay share per chapter",
            "type": "boolean",
            "description": "Return `chapterReplayShare[]` — for every chapter, its `avgReplayValue` and its `replayShare` (fraction of the video's total replay intensity), plus `topChapterTitle`.\n\nAnswers \"which section actually holds people\" in one column. Needs both a heatmap and chapters; returns an empty array if either is missing. Default: on.",
            "default": true
          },
          "attachTranscriptToPeaks": {
            "title": "💬 Attach spoken text to each clip window",
            "type": "boolean",
            "description": "Fill `transcriptText` on every clip window with the caption cues that overlap that window — the words actually spoken in the most-rewatched seconds.\n\nTurn off to skip the caption download entirely. Default: on.",
            "default": true
          },
          "includeFullTranscript": {
            "title": "📜 Return the full transcript",
            "type": "boolean",
            "description": "Return the complete `transcript[]` on the row. Each cue is `{start, dur, end, text, startSeconds, endSeconds}`.\n\nTurn off to keep rows small when you only care about the clip windows. Default: on.",
            "default": true
          },
          "transcriptLanguage": {
            "title": "🌐 Caption language",
            "type": "string",
            "description": "ISO code of the caption track to use, e.g. `en`, `es`, `de`. Leave empty to use the video's own language, then English, then whatever track exists.\n\nIf the requested language has no track, `noTranscriptReason` is set to `no_caption_track_in_requested_language` rather than silently falling back.",
            "default": ""
          },
          "preferHumanCaptions": {
            "title": "🙋 Prefer human-written captions",
            "type": "boolean",
            "description": "On: use creator-uploaded subtitles when they exist and fall back to auto-generated ones. Off: prefer the auto-generated track (usually denser timing, better for clip alignment). The original Actor hardcoded human-first with no way to invert. Default: on.",
            "default": true
          },
          "skipVideosWithoutHeatmap": {
            "title": "🚫 Skip videos with no replay data",
            "type": "boolean",
            "description": "Mark videos that return no heatmap as skipped instead of emitting a full row. Skipped rows are still written to the dataset with `skippedReason: \"no_heatmap\"` and `success: false`, and are **not** billed. Default: off.",
            "default": false
          },
          "skipVideosWithoutChapters": {
            "title": "🚫 Skip videos with no chapters",
            "type": "boolean",
            "description": "Same as above for chapter markers: `skippedReason: \"no_chapters\"`, `success: false`, not billed. Roughly 1 in 3 videos has no chapters. Default: off.",
            "default": false
          },
          "requestDelaySeconds": {
            "title": "⏳ Delay between videos (seconds)",
            "minimum": 0,
            "maximum": 60,
            "type": "number",
            "description": "Pause between videos. The original Actor slept a random 2–5 s on every video regardless of proxy. With residential proxy the pause buys little, so lower it for speed. Default: 2.",
            "default": 2
          },
          "proxyConfiguration": {
            "title": "🔒 Proxy",
            "type": "object",
            "description": "**Residential is the default and you should keep it.** YouTube bot-walls datacenter addresses with \"Sign in to confirm you're not a bot\".\n\nMeasured: an 8-video batch over the Apify datacenter pool returned data for 1 of 8 videos, residential for 7 of 8. Running with **no** proxy uses the container's own datacenter IP — in a 4-video test run that hit the bot wall on 2 of the 4 videos.\n\nBoth of those were recovered, because on a bot wall this Actor retries on a **fresh residential session** rather than on the same burnt exit node. Residential traffic costs more per GB; that cost is what makes the run return data.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}