{ "openapi": "3.0.1", "info": { "title": "YouTube Opportunity Finder", "description": "Find YouTube video ideas with high audience demand and low creator competition — before they saturate. Scores every topic for demand vs. competition, spots gaps in your competitor's channels, and delivers ready-to-use titles, thumbnails, and hooks (AI) straight to Notion.", "version": "0.0", "x-build-id": "es60cDGjyRV76vQOd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/apt_marble~youtube-opportunity-finder/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-apt_marble-youtube-opportunity-finder", "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/apt_marble~youtube-opportunity-finder/runs": { "post": { "operationId": "runs-sync-apt_marble-youtube-opportunity-finder", "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/apt_marble~youtube-opportunity-finder/run-sync": { "post": { "operationId": "run-sync-apt_marble-youtube-opportunity-finder", "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", "required": [ "seedKeywords" ], "properties": { "seedKeywords": { "title": "Niches / seed keywords", "minItems": 1, "type": "array", "description": "The niches to mine for opportunities. Each tick expands every keyword into many candidate search queries (autocomplete + related searches), tracks the videos found, and scores demand vs competition to surface what you should publish next.", "default": [ "world cup 2026", "fifa 2026", "champions league" ], "items": { "type": "string" } }, "competitorChannels": { "title": "Competitor channels (Content Gap engine)", "type": "array", "description": "Optional. Channel URLs, @handles, or channel IDs (e.g. https://youtube.com/@MrBeast, @mkbhd, UCX6OQ3DkcsbYNE6H8uQQuVA). For each, the actor finds high-value topics in your niche that the channel has NOT covered — \"you are missing these opportunities\".", "default": [], "items": { "type": "string" } }, "notionConnector": { "title": "Notion connector", "type": "string", "description": "Connect your Notion workspace. Content opportunities, emerging topics, viral opportunities, competitor gaps and daily/weekly reports are written here automatically. Leave empty to run in dry-run mode (reports go to a dataset instead of Notion)." }, "notionParentPage": { "title": "Notion parent page (ID or URL)", "type": "string", "description": "The page under which the opportunity workspace (Content Opportunities, Emerging Topics, Viral Opportunities, Competitor Gaps, Daily/Weekly Reports) is built. Required when a Notion connector is set." }, "opportunityScoreMin": { "title": "Opportunity: min score", "minimum": 0, "maximum": 100, "type": "integer", "description": "A topic must reach this opportunity score (0–100) to bill as a discovered opportunity. Lower = more (lower-confidence) opportunities.", "default": 55 }, "demandScoreMin": { "title": "Opportunity: min demand score", "minimum": 0, "maximum": 100, "type": "integer", "description": "A topic must also reach this demand score (0–100) before it can bill as an opportunity, so low-demand low-competition noise is filtered out.", "default": 30 }, "emergingGrowthMin": { "title": "Emerging topic: min growth score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum growth score (0–100, demand vs the topic's baseline) for an Emerging Topic event. Needs ≥3 ticks of history.", "default": 45 }, "viralOpportunityScoreMin": { "title": "Viral opportunity: min score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum opportunity score (0–100) for the premium Viral Opportunity event (also requires Low competition and strong growth).", "default": 85 }, "competitorGapScoreMin": { "title": "Competitor gap: min value", "minimum": 0, "maximum": 100, "type": "integer", "description": "A missing topic must reach this opportunity score (0–100) to bill as a Competitor Gap.", "default": 50 }, "topicMinVideos": { "title": "Topic: min videos", "minimum": 2, "type": "integer", "description": "How many related videos must cluster together to form a scoreable topic.", "default": 3 }, "opportunityCooldownHours": { "title": "Opportunity cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same opportunity can bill again (unless its score escalates).", "default": 72 }, "emergingTopicCooldownHours": { "title": "Emerging-topic cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same emerging topic can bill again (unless its growth escalates).", "default": 48 }, "competitorGapCooldownHours": { "title": "Competitor-gap cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same channel+topic gap can bill again (unless its value escalates).", "default": 168 }, "viralOpportunityCooldownHours": { "title": "Viral-opportunity cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same viral opportunity can bill again (unless its score escalates).", "default": 48 }, "expandTopics": { "title": "Expand niches into candidate topics", "type": "boolean", "description": "Use YouTube autocomplete + related searches to expand each seed niche into many candidate search queries (the topic-discovery engine). Turn off to search only the exact seed keywords.", "default": true }, "maxCandidateTopicsPerSeed": { "title": "Max candidate topics per niche", "minimum": 0, "maximum": 200, "type": "integer", "description": "How many autocomplete-expanded queries to actually search per seed niche each tick. Higher = broader discovery, more data requests.", "default": 15 }, "maxVideosPerKeyword": { "title": "Max videos discovered per query", "minimum": 1, "maximum": 200, "type": "integer", "description": "How many videos to add to the tracked set per search query each tick.", "default": 15 }, "enableContentGap": { "title": "Enable Content Gap engine", "type": "boolean", "description": "Analyze the competitor channels above for missing high-value topics. No effect if no competitor channels are provided.", "default": true }, "enableTitleGen": { "title": "Enable AI title / thumbnail / hook generation", "type": "boolean", "description": "For each opportunity, generate 10 titles, 5 thumbnail concepts and 5 hook ideas. Uses an AI model when the OF_LLM_API_KEY environment variable is set (e.g. Kimi/Moonshot), otherwise falls back to deterministic templates.", "default": true }, "maxChannelVideos": { "title": "Competitor: videos analyzed per channel", "minimum": 5, "maximum": 200, "type": "integer", "description": "How many recent uploads to read per competitor channel when computing its covered topics.", "default": 40 }, "discoverySort": { "title": "Discover by", "enum": [ "viewCount", "relevance", "uploadDate", "rating" ], "type": "string", "description": "How to pick videos to track. 'View count' (recommended) tracks videos with real view momentum so demand is measurable; 'Upload date' tracks the newest (often near-zero-view) uploads.", "default": "viewCount" }, "discoveryDateFilter": { "title": "Discover within", "enum": [ "today", "week", "month", "year", "" ], "type": "string", "description": "Only discover videos uploaded within this window. 'This month' is a good default for opportunity finding (recent supply without being too sparse).", "default": "month" }, "runMode": { "title": "Run mode", "enum": [ "tick", "backfill", "dryRun", "reporterTest" ], "type": "string", "description": "tick = a normal scheduled run. backfill = discover + snapshot only (seed history). dryRun = force local reporter. reporterTest = probe the Notion workspace.", "default": "tick" }, "reportHourUtc": { "title": "Daily/weekly report hour (UTC)", "minimum": 0, "maximum": 23, "type": "integer", "description": "The UTC hour at which daily and weekly reports are published. Match this to your daily schedule's hour.", "default": 8 }, "weeklyReportDow": { "title": "Weekly report day of week (0=Sun)", "minimum": 0, "maximum": 6, "type": "integer", "description": "Day of week the weekly report is published (0 = Sunday … 6 = Saturday).", "default": 1 }, "country": { "title": "Country (gl)", "type": "string", "description": "Two-letter country code for region-specific results.", "default": "us" }, "language": { "title": "Language (hl)", "type": "string", "description": "Two-letter language code for results.", "default": "en" }, "resetState": { "title": "Start fresh (reset stored data)", "type": "boolean", "description": "Turn ON for ONE run to wipe all stored data (tracked videos, history, baselines, cached Notion pages) and rebuild from scratch — useful after you change niches or your Notion page. ⚠️ Turn it OFF again after that run, or every run resets and growth signals never accumulate.", "default": false }, "discoveryPagesPerKeyword": { "title": "Discovery pages per query", "minimum": 1, "maximum": 10, "type": "integer", "description": "Operator-only (hidden; set via JSON). How many search-result pages to page through per query during discovery.", "default": 1 }, "maxTrackedVideos": { "title": "Max tracked videos", "minimum": 10, "maximum": 100000, "type": "integer", "description": "Operator-only (hidden; set via JSON). The tracked set is capped here; lowest-value videos are evicted when exceeded.", "default": 4000 }, "snapshotConcurrency": { "title": "Snapshot concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Operator-only (hidden; set via JSON). How many tracked videos to snapshot in parallel each tick.", "default": 4 }, "snapshotProxyFallback": { "title": "Proxy fallback for view counts", "type": "boolean", "description": "Internal: retries zeroed view counts through the premium proxy for accuracy. Hidden from the input form; always on.", "default": true }, "maxEventsPerTick": { "title": "Max billable events per tick", "minimum": 0, "type": "integer", "description": "Operator-only (hidden; set via JSON). Safety cap on how many billable events a single run can emit. The highest-value events are kept; the rest can re-emit on a later tick. Set 0 for unlimited.", "default": 100 }, "forceDaily": { "title": "Force a daily report now (operator)", "type": "boolean", "description": "Operator-only (hidden from the form; set via JSON input). Fires a daily report on this run regardless of the schedule. If left on it bills a daily report every run.", "default": false }, "forceWeekly": { "title": "Force a weekly report now (operator)", "type": "boolean", "description": "Operator-only (hidden from the form; set via JSON input). Fires a weekly report on this run regardless of the schedule. If left on it bills a weekly report every run.", "default": false } } }, "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 } } } } } } } } } }