# Youtube Trend Intelligence Workspace (`apt_marble/youtube-trend-intelligence-workspace`) Actor ๐Ÿ“ˆ Your automated YouTube trend analyst. Discovers emerging trends, tracks view momentum & acceleration every hour, and auto-writes breakout alerts, rising creators & content opportunities straight to your Notion workspace. ๐Ÿš€ - **URL**: https://apify.com/apt\_marble/youtube-trend-intelligence-workspace.md - **Developed by:** [Hamza](https://apify.com/apt_marble) (community) - **Categories:** SEO tools, Social media, Automation - **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $100.00 / 1,000 daily intelligence reports This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## ๐Ÿ“ˆ YouTube Trend Intelligence Workspace **Your automated YouTube trend analyst โ€” working 24/7.** It discovers emerging topics, tracks their growth hour by hour, scores virality and momentum from that history, and writes organized research reports straight into your **Notion** workspace. Open Notion every morning and immediately see **what's about to blow up** โ€” breakout videos, emerging trends, rising creators, and content opportunities โ€” without ever opening YouTube analytics yourself. > โš ๏ธ **Setup is two steps (required):** **1)** connect your Notion workspace, **2)** run it on an **hourly schedule**. This is a continuous platform โ€” a single run can't measure momentum. See [Quick start](#-quick-start-2-steps). --- ### The problem every trend tool has Every other YouTube tool shows you **snapshots**: current views, current likes, current rankings. A snapshot is a photo. It can't tell you: - What topic is *starting* to explode? - Which creators are gaining momentum *right now*? - Which niche is accelerating fastest? - Which video will likely go viral *next week*? - What should I make a video about *tomorrow*? **This is not a scraper โ€” it's an early-warning system.** A scraper hands you a spreadsheet of *today's* numbers. This watches the *same* videos hour after hour and reads their **trajectory** โ€” how fast they're growing (velocity), whether that growth is *speeding up* (acceleration), and how that stacks up against everything else (a 0โ€“100 viral score). Because **attention accelerates before it explodes**, you catch a video *while it's still small* โ€” not after it already trended. No YouTube API exposes this; it can only come from continuous tracking โ€” the compounding history this actor quietly builds into your private moat. ### What it actually does It runs as a single Actor on an **hourly schedule**. Each run is one *tick*, and across ticks it builds a private, compounding dataset of growth history โ€” your moat. Every tick it: 1. **Discovers** the highest-momentum videos for your seed keywords. 2. **Snapshots** every tracked video's views / likes / comments and stores the time series. 3. **Computes** velocity, acceleration, engagement, freshness โ†’ a **viral score**. 4. **Clusters** related videos into **named trends** (e.g. several "World Cup 2026" videos โ†’ one "World Cup 2026" trend with a trend score). 5. **Detects** breakouts, rising creators, and **low-competition / high-growth content opportunities**. 6. **Writes** the results into your Notion workspace as clean, dated research pages. You only pay for the **intelligence it produces** โ€” never for the raw scraping behind it (see [Pricing](#-pricing--you-pay-for-insight-not-scraping)). ### Why you need it โ€” and who it's for | You are aโ€ฆ | You getโ€ฆ | |---|---| | **Content creator** | Breakout topics & low-competition content ideas *before* the niche gets crowded โ€” with ready-to-use titles | | **Marketing / social agency** | Always-on trend monitoring and auto-generated client-ready reports, hands-free | | **SEO team** | Emerging search topics and rising video queries as they start moving | | **Startup / brand** | Early market & consumer-interest signals in your category | | **Investor / analyst** | Momentum and sentiment shifts across consumer topics, tracked over time | The difference: a scraper hands you a spreadsheet of *current* numbers. This hands you a **morning briefing of what's changing** โ€” the same thing a full-time analyst would produce, automatically, in Notion. ### ๐Ÿ“‚ See it live A real workspace this actor produced: **[Trend Intelligence Workspace โ€” live example](https://app.notion.com/p/Trend-Intelligence-Workspace-37e38f6c6ff180d79e21e7db3b551364)** ### โšก Quick start (2 steps) 1. **Connect Notion** โ€” in the input, pick your **Notion connector** and paste a **Notion parent page** (URL or ID) where reports should live. *(First time? In Apify โ†’ **Settings โ†’ Integrations โ†’ MCP connectors**, authorize **Notion** and grant it access to that page.)* 2. **Schedule it hourly** โ€” **Schedules โ†’ Create โ†’ Add Actor โ†’** cron `0 * * * *`, **Run mode = `tick`**. Done โ€” reports start flowing into Notion. > Clicking **Start** once runs a single tick and produces **no insights and no charge** (momentum needs โ‰ฅ2 hourly snapshots). To verify Notion end-to-end immediately, run once with **Run mode = `reporterTest`** โ€” it creates the section pages. ### ๐Ÿงช Try it ```json { "seedKeywords": ["world cup 2026", "ai agents", "air fryer recipes"], "notionConnector": "", "notionParentPage": "https://www.notion.so/your-trend-intelligence-page" } ```` Within a day your Notion fills with real, momentum-ranked intelligence (swap the keywords for anything you want to monitor). ### What lands in your Notion The actor builds and maintains this structure under your page: ``` Your Trend Intelligence page โ”œโ”€โ”€ ๐Ÿ“… Daily Reports โ€” a morning briefing: top trends, fastest videos, opportunities, niche heatmap โ”œโ”€โ”€ ๐Ÿ—“๏ธ Weekly Reports โ€” the week's roundup โ”œโ”€โ”€ ๐Ÿ“ˆ Emerging Trends โ€” each detected trend: member videos, combined velocity & acceleration, score โ”œโ”€โ”€ ๐Ÿš€ Breakout Videos โ€” videos exploding now: +views/hour, acceleration, viral score โ”œโ”€โ”€ โญ Rising Creators โ€” channels growing unusually fast vs. their own baseline โ””โ”€โ”€ ๐Ÿ’ก Content Opportunities โ€” low-competition, high-growth topics + ready-to-use title ideas ``` Example pages it writes: - **๐Ÿš€ Breakout** โ€” *"World Cup 2026: USA vs Brazil โ€” Extended Highlights" โ€” +24,000 views/hour ยท acceleration +210% ยท viral 96/100 ยท Status: Exploding* - **๐Ÿ“ˆ Trend** โ€” *"AI Agents" โ€” 30 videos ยท 8.4M combined views ยท +320% growth ยท top channels & member links* - **๐Ÿ’ก Opportunity** โ€” *"Air Fryer Recipes โ€” Low competition ยท High velocity ยท score 81"* + 5 suggested titles ### How it works Every hour it runs one **tick**: it surfaces the videos gaining traction across your niches, records where each one stands, compares against everything it has tracked before, and turns the change into momentum โ€” then publishes the resulting insights to Notion. ``` Discover movers โ†’ Track hourly โ†’ Score momentum โ†’ Detect trends & opportunities โ†’ Report to Notion ``` What makes it reliable (and different from a scraper): - **A compounding, private dataset.** It remembers each video's full history across runs, so the picture sharpens every hour โ€” a depth no one-off scrape can reach. That history is your moat. - **Explainable scoring.** Velocity, acceleration, engagement and freshness combine into a transparent 0โ€“100 viral score, and related videos roll up into named trends โ€” no black box. - **No noise, no surprise charges.** Built-in de-duplication surfaces (and bills) each breakout, trend, or opportunity *once* โ€” re-raising it only when it genuinely escalates. - **Efficient by design.** Data collection is optimized so typical runs cost next to nothing to operate. - **Native, secure Notion delivery.** Reports are written through Apify's MCP connectors using *your* authorized Notion access โ€” your credentials never touch the actor. ### โš™๏ธ Inputs | Input | What it does | |---|---| | **Seed keywords / niches** | The topics to monitor (each gets its own discovery + tracking) | | **Notion connector** | Your authorized Notion connection โ€” where reports are written | | **Notion parent page** | The page the workspace is built under (URL or ID) | | **Discover by / within** | Track view-count *movers* (default) vs newest uploads; time window | | **Detection thresholds** | How aggressive billable detection is (breakout / trend / opportunity / rising-creator) | | **Cooldowns** | How long before the same insight can re-report | | **Report timing & locale** | Daily/weekly publish hour (UTC), country & language | ### ๐Ÿ”— Notion setup 1. In **Apify Console โ†’ Settings โ†’ Integrations โ†’ MCP connectors**, authorize a **Notion** connector and grant it access to the page you'll use. 2. In the input, select that **Notion connector** and paste your **Notion parent page** URL. 3. Run once with **Run mode = `reporterTest`** to confirm the connection and create the six section pages. Your Notion credentials never touch the actor โ€” Apify's MCP proxy injects them at runtime and access ends when the run ends. ### โฐ Scheduling Create an Apify **Schedule** running the actor hourly (`0 * * * *`) with **Run mode = `tick`**. - Configure **non-overlapping** runs (concurrency 1) โ€” two ticks must never write state simultaneously. - Daily & weekly reports are paced **inside** the actor (by elapsed time), so a missed hourly run defers a report rather than losing or duplicating it. - Warm-up: breakouts need โ‰ฅ2โ€“3 ticks of history; the first daily report publishes ~24h in. ### ๐Ÿ’ณ Pricing โ€” you pay for insight, not scraping Raw work is **never billable**: discovery, scraping, snapshots, and internal analytics are infrastructure. You're charged only when the platform produces a **meaningful insight**, and the same insight is **not re-billed every hour**. | Event | Fires when | |---|---| | **Breakout alert** | A video's view velocity *and* acceleration cross the thresholds | | **Emerging trend** | Multiple related videos accelerate together as a named trend | | **Rising creator** | A channel grows unusually fast vs. its baseline | | **Content opportunity** | A low-competition, high-growth topic is identified | | **Daily report** | Once per day | | **Weekly report** | Once per week | ### โ“ FAQ **Why no results on the first run?** Momentum is measured *between* hourly snapshots โ€” velocity needs 2 ticks, acceleration 3, the first daily report ~24h. Run it on the hourly schedule and it fills in. **Do I need a YouTube API key?** No. You only connect Notion. **Will it spam my Notion / over-bill me?** No โ€” built-in de-duplication ensures each insight is reported (and billed) once, then suppressed until it meaningfully changes. **Can I monitor anything?** Yes โ€” any keywords/niches. The examples are just examples. **Where does the data come from?** Public YouTube data, collected efficiently. # Actor input Schema ## `seedKeywords` (type: `array`): The topics to monitor. Each tick discovers fresh videos for every keyword and tracks their growth over time. ## `notionConnector` (type: `string`): Connect your Notion workspace. Daily reports, breakout alerts, emerging trends, rising creators and content opportunities are written here automatically. Leave empty to run in dry-run mode (reports go to a dataset instead of Notion). ## `notionParentPage` (type: `string`): The page under which the Trend Intelligence workspace (Daily Reports, Breakout Videos, Emerging Trends, โ€ฆ) is built. Required when a Notion connector is set. ## `breakoutViewsPerHour` (type: `integer`): A video must exceed this view velocity to qualify as a breakout. Lower = more breakout alerts. ## `breakoutAccel` (type: `integer`): Minimum view acceleration (growth of growth, views/hourยฒ) for a breakout. ## `viralScoreMin` (type: `integer`): Minimum viral score (0โ€“100) for a breakout alert. ## `trendScoreMin` (type: `integer`): Minimum trend score (0โ€“100) for an emerging-trend event. ## `trendMinVideos` (type: `integer`): How many related videos must cluster together to form a trend. ## `opportunityScoreMin` (type: `integer`): Minimum opportunity score (0โ€“100) for a content-opportunity event. ## `risingCreatorMomentumMin` (type: `integer`): Minimum momentum score (0โ€“100) for a rising-creator event. ## `breakoutCooldownHours` (type: `integer`): How long before the same breakout video can bill again (unless it escalates). ## `trendCooldownHours` (type: `integer`): How long before the same emerging trend can bill again (unless its trend score escalates). ## `risingCreatorCooldownHours` (type: `integer`): How long before the same rising creator can bill again (unless its momentum escalates). ## `opportunityCooldownHours` (type: `integer`): How long before the same content opportunity can bill again (unless its score escalates). ## `runMode` (type: `string`): tick = a normal hourly run. backfill = discover + snapshot only (seed history). dryRun = force local reporter. reporterTest = probe the Notion workspace. ## `enablePremium` (type: `boolean`): Rising-creator detection, niche heatmap and content-idea generation. ## `forceDaily` (type: `boolean`): 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. ## `forceWeekly` (type: `boolean`): 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. ## `resetState` (type: `boolean`): Turn ON for ONE run to wipe all stored data (tracked videos, history, and cached Notion pages) and rebuild from scratch โ€” useful after you change your keywords or Notion page. โš ๏ธ Turn it OFF again after that run, or every run will reset and momentum (trends, breakouts, reports) will never accumulate. ## `discoverySort` (type: `string`): How to pick videos to track. 'View count' (recommended) tracks videos with real view momentum so velocity is measurable; 'Upload date' tracks the newest (often near-zero-view) uploads. ## `discoveryDateFilter` (type: `string`): Only discover videos uploaded within this window. ## `maxVideosPerKeyword` (type: `integer`): How many videos to add to the tracked set per keyword each tick. ## `discoveryPagesPerKeyword` (type: `integer`): Operator-only (hidden; set via JSON). How many search-result pages to page through per keyword during discovery. ## `maxTrackedVideos` (type: `integer`): Operator-only (hidden; set via JSON). The tracked set is capped here; lowest-value videos are evicted when exceeded. ## `snapshotConcurrency` (type: `integer`): Operator-only (hidden; set via JSON). How many tracked videos to snapshot in parallel each tick. ## `snapshotProxyFallback` (type: `boolean`): Internal: retries zeroed view counts through the premium proxy for accuracy. Hidden from the input form; always on. ## `maxEventsPerTick` (type: `integer`): 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. Protects against runaway billing from a data anomaly. Set 0 for unlimited. ## `reportHourUtc` (type: `integer`): The UTC hour at which daily and weekly reports are published. ## `weeklyReportDow` (type: `integer`): Day of week the weekly report is published (0 = Sunday โ€ฆ 6 = Saturday). ## `country` (type: `string`): Two-letter country code for region-specific results. ## `language` (type: `string`): Two-letter language code for results. ## Actor input object example ```json { "seedKeywords": [ "World cup 2026", "video games", "air fryer" ], "breakoutViewsPerHour": 1500, "breakoutAccel": 300, "viralScoreMin": 60, "trendScoreMin": 40, "trendMinVideos": 3, "opportunityScoreMin": 40, "risingCreatorMomentumMin": 50, "breakoutCooldownHours": 24, "trendCooldownHours": 48, "risingCreatorCooldownHours": 48, "opportunityCooldownHours": 72, "runMode": "tick", "enablePremium": true, "forceDaily": false, "forceWeekly": false, "resetState": false, "discoverySort": "viewCount", "discoveryDateFilter": "week", "maxVideosPerKeyword": 20, "discoveryPagesPerKeyword": 2, "maxTrackedVideos": 5000, "snapshotConcurrency": 4, "snapshotProxyFallback": true, "maxEventsPerTick": 100, "reportHourUtc": 8, "weeklyReportDow": 1, "country": "us", "language": "en" } ``` # Actor output Schema ## `events` (type: `string`): The feed of billable + non-billable intelligence events produced this run. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "seedKeywords": [ "World cup 2026", "video games", "air fryer" ] }; // Run the Actor and wait for it to finish const run = await client.actor("apt_marble/youtube-trend-intelligence-workspace").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "seedKeywords": [ "World cup 2026", "video games", "air fryer", ] } # Run the Actor and wait for it to finish run = client.actor("apt_marble/youtube-trend-intelligence-workspace").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "seedKeywords": [ "World cup 2026", "video games", "air fryer" ] }' | apify call apt_marble/youtube-trend-intelligence-workspace --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=apt_marble/youtube-trend-intelligence-workspace", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Youtube Trend Intelligence Workspace", "description": "๐Ÿ“ˆ Your automated YouTube trend analyst. Discovers emerging trends, tracks view momentum & acceleration every hour, and auto-writes breakout alerts, rising creators & content opportunities straight to your Notion workspace. ๐Ÿš€", "version": "0.0", "x-build-id": "sxzvCYKhCJRGCuTCS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/apt_marble~youtube-trend-intelligence-workspace/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-apt_marble-youtube-trend-intelligence-workspace", "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-trend-intelligence-workspace/runs": { "post": { "operationId": "runs-sync-apt_marble-youtube-trend-intelligence-workspace", "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-trend-intelligence-workspace/run-sync": { "post": { "operationId": "run-sync-apt_marble-youtube-trend-intelligence-workspace", "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": "Seed keywords / niches", "minItems": 1, "type": "array", "description": "The topics to monitor. Each tick discovers fresh videos for every keyword and tracks their growth over time.", "default": [ "World cup 2026", "video games", "air fryer" ], "items": { "type": "string" } }, "notionConnector": { "title": "Notion connector", "type": "string", "description": "Connect your Notion workspace. Daily reports, breakout alerts, emerging trends, rising creators and content opportunities 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 Trend Intelligence workspace (Daily Reports, Breakout Videos, Emerging Trends, โ€ฆ) is built. Required when a Notion connector is set." }, "breakoutViewsPerHour": { "title": "Breakout: min views/hour", "minimum": 0, "type": "integer", "description": "A video must exceed this view velocity to qualify as a breakout. Lower = more breakout alerts.", "default": 1500 }, "breakoutAccel": { "title": "Breakout: min acceleration", "minimum": 0, "type": "integer", "description": "Minimum view acceleration (growth of growth, views/hourยฒ) for a breakout.", "default": 300 }, "viralScoreMin": { "title": "Breakout: min viral score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum viral score (0โ€“100) for a breakout alert.", "default": 60 }, "trendScoreMin": { "title": "Trend: min trend score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum trend score (0โ€“100) for an emerging-trend event.", "default": 40 }, "trendMinVideos": { "title": "Trend: min videos", "minimum": 2, "type": "integer", "description": "How many related videos must cluster together to form a trend.", "default": 3 }, "opportunityScoreMin": { "title": "Opportunity: min score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum opportunity score (0โ€“100) for a content-opportunity event.", "default": 40 }, "risingCreatorMomentumMin": { "title": "Rising creator: min momentum", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum momentum score (0โ€“100) for a rising-creator event.", "default": 50 }, "breakoutCooldownHours": { "title": "Breakout cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same breakout video can bill again (unless it escalates).", "default": 24 }, "trendCooldownHours": { "title": "Trend cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same emerging trend can bill again (unless its trend score escalates).", "default": 48 }, "risingCreatorCooldownHours": { "title": "Rising-creator cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same rising creator can bill again (unless its momentum escalates).", "default": 48 }, "opportunityCooldownHours": { "title": "Opportunity cooldown (hours)", "minimum": 0, "type": "integer", "description": "How long before the same content opportunity can bill again (unless its score escalates).", "default": 72 }, "runMode": { "title": "Run mode", "enum": [ "tick", "backfill", "dryRun", "reporterTest" ], "type": "string", "description": "tick = a normal hourly run. backfill = discover + snapshot only (seed history). dryRun = force local reporter. reporterTest = probe the Notion workspace.", "default": "tick" }, "enablePremium": { "title": "Enable premium features", "type": "boolean", "description": "Rising-creator detection, niche heatmap and content-idea generation.", "default": true }, "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 }, "resetState": { "title": "Start fresh (reset stored data)", "type": "boolean", "description": "Turn ON for ONE run to wipe all stored data (tracked videos, history, and cached Notion pages) and rebuild from scratch โ€” useful after you change your keywords or Notion page. โš ๏ธ Turn it OFF again after that run, or every run will reset and momentum (trends, breakouts, reports) will never accumulate.", "default": false }, "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 velocity 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.", "default": "week" }, "maxVideosPerKeyword": { "title": "Max videos discovered per keyword", "minimum": 1, "maximum": 200, "type": "integer", "description": "How many videos to add to the tracked set per keyword each tick.", "default": 20 }, "discoveryPagesPerKeyword": { "title": "Discovery pages per keyword", "minimum": 1, "maximum": 10, "type": "integer", "description": "Operator-only (hidden; set via JSON). How many search-result pages to page through per keyword during discovery.", "default": 2 }, "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": 5000 }, "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. Protects against runaway billing from a data anomaly. Set 0 for unlimited.", "default": 100 }, "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.", "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" } } }, "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 } } } } } } } } } } ```