{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Related Videos Graph Crawler",
    "description": "Crawl YouTube's related-videos graph multi-hop deep from any seed video. BFS traversal with configurable depth + branch + node cap. Each row carries depth, parent video, and full discovery path. Built for content strategy, brand safety, and recommendation-algorithm research.",
    "version": "1.0",
    "x-build-id": "aBwkzqX67tU4u4xxf"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~youtube-related-videos-crawler/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-youtube-related-videos-crawler",
        "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/sian.agency~youtube-related-videos-crawler/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-youtube-related-videos-crawler",
        "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/sian.agency~youtube-related-videos-crawler/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-youtube-related-videos-crawler",
        "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": {
          "videoId": {
            "title": "🎬 Seed video ID or YouTube URL (single-seed mode)",
            "type": "string",
            "description": "🎬 **Use this for a single-seed crawl.** Leave empty if you want to use the bulk `seedVideoIds` field below.\n\nAccepts:\n- 11-character video ID: `dQw4w9WgXcQ`\n- Full URL: `https://www.youtube.com/watch?v=dQw4w9WgXcQ`\n- Short URL: `https://youtu.be/dQw4w9WgXcQ`\n- Shorts URL: `https://www.youtube.com/shorts/X4dGtpUD3gA`\n\n💡 **TIP:** Start with `maxDepth=1` and `maxBranchPerNode=10` for a feel of the neighborhood (~10 rows). Move to `maxDepth=2` (~100 rows) or `maxDepth=3` (~500+ rows) to crawl deeper."
          },
          "seedVideoIds": {
            "title": "📚 Bulk seed video IDs (one per line, or comma-separated)",
            "type": "string",
            "description": "📚 **Use this for a bulk-seed crawl.** Leave empty if you use the single `videoId` field above.\n\nEach seed gets its own BFS graph crawl. Dedup is global across all seeds — a video discovered via Seed A and Seed B is emitted once with its earliest `discoveryPath`.\n\nAccepts video IDs, full watch URLs, short URLs, or Shorts URLs (one per line, or comma-separated). Up to 50 seeds per run.\n\n💡 **TIP:** For a balanced topical-cluster study, pass 5-10 well-chosen seeds at `maxDepth=2`."
          },
          "maxDepth": {
            "title": "🔁 Max hop depth",
            "minimum": 0,
            "maximum": 4,
            "type": "integer",
            "description": "🔁 **How many hops deep to crawl.** Depth 0 = seed only. Depth 1 = seed + its direct related videos. Depth 2 = seed + neighbors-of-neighbors. Depth 3 = three hops out (~500-1100 rows per seed with branch=10).\n\nGeometric growth: rows ≈ `1 + branch + branch² + ... + branch^maxDepth`. The `maxNodes` cap below stops runaway crawls.\n\n- **Default:** 1 (~10 rows)\n- **Min:** 0 (seed only — emits a single row, useful for ID validation)\n- **Max:** 4 (use with low branch and tight maxNodes)",
            "default": 1
          },
          "maxBranchPerNode": {
            "title": "🌿 Max branch factor per node",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "🌿 **How many related videos to follow from each crawled node.** Higher = wider local sampling; lower = narrower, deeper chains.\n\n- `1` = follow only the top related video per node — gives chain-like exploration\n- `10` = balanced topical neighborhood (default)\n- `20` = full breadth (use sparingly — each /related call returns ~20 items)\n\n💡 **TIP:** For a topical-cluster study, branch=10 is the sweet spot. For chain-style algorithm tracing, set branch=3 with depth=4.",
            "default": 10
          },
          "maxNodes": {
            "title": "🛡 Max nodes (safety cap)",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "🛡 **Hard cap on total unique videos discovered across the crawl.** BFS stops the moment this cap is reached, even mid-level.\n\nProtects against geometric explosion: depth=4 × branch=10 = up to 11,111 nodes without a cap. Keeping `maxNodes` realistic prevents quota burn.\n\n- **Default:** 500 (covers most depth=2 crawls + most depth=3 crawls with branch=10)\n- **Min:** 1\n- **Max:** 5,000",
            "default": 500
          },
          "maxPagesPerNode": {
            "title": "📄 Max continuation pages per node",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "📄 **How many `/related` continuation pages to pull per crawled node** (each page returns ~20 fresh items). Multiplies the local sample at each hop without going deeper.\n\n- **Default:** 1 (single page per node — typical)\n- **Min:** 1\n- **Max:** 5 (~100 items per node)\n\n💡 **TIP:** Leave at 1 unless you specifically want a fatter local neighborhood from the seed.",
            "default": 1
          },
          "includeShorts": {
            "title": "🩳 Include Shorts from `shorts_listing` carousels",
            "type": "boolean",
            "description": "🩳 **When the upstream returns a `shorts_listing` carousel** (e.g. \"Shorts remixing this video\"), unpack and emit each Short as a row.\n\n- `true` = emit Shorts (default)\n- `false` = skip Shorts; only emit standard `video` items\n\nShorts are NOT traversed (no `/related` call is made on them) — they are leaf nodes in the graph. Only the carousel videos themselves are emitted.",
            "default": true
          },
          "includePlaylists": {
            "title": "📋 Include playlist items",
            "type": "boolean",
            "description": "📋 **When the upstream returns `playlist` items** in the related-videos list (e.g. \"Mix - Artist Name\"), emit them as leaf rows.\n\n- `true` = emit playlist items as rows (the cover videoId is captured)\n- `false` = skip playlists entirely (default — playlists are not real related-video nodes; their cover videoId is just a thumbnail anchor)\n\nPlaylists are NEVER traversed (no `/related` call is made on the cover videoId).",
            "default": false
          },
          "geo": {
            "title": "🌍 Country (optional, ISO 3166-1 alpha-2)",
            "type": "string",
            "description": "🌍 **Optional.** Two-letter country code to localize the recommendation graph. Defaults to `US`.\n\nExamples: `US` (United States), `GB` (United Kingdom), `IN` (India), `BR` (Brazil), `DE` (Germany), `JP` (Japan), `KR` (Korea), `MX` (Mexico).",
            "default": "US"
          },
          "lang": {
            "title": "🗣 Language (optional, ISO 639-1)",
            "type": "string",
            "description": "🗣 **Optional.** Two-letter language code for localized labels. Defaults to `en`.\n\nExamples: `en`, `es`, `pt`, `hi`, `ja`, `ko`.",
            "default": "en"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}