--- name: optimize-ad-schedule description: >- Finds which hours and weekdays convert at acceptable cost and shifts spend into them: builds an hour-by-day performance matrix from 30-60 days of data, classifies each slot by deviation from the campaign average, then either applies per-slot bid adjustments (Manual CPC campaigns) or pauses only confirmed dead windows with -100% (Smart Bidding, which ignores every other schedule percentage). Use it when time-of-day CPA/ROAS swings 30%+ around the average, when a constrained budget burns out before peak hours, or on a quarterly time-pattern refresh. Not for the broader multi-dimension modifier pass (optimize-bid-modifiers), strategy or target changes (select-a-bidding-strategy / calculate-bid-targets), or budget sizing (allocate-budget-across-campaigns). --- # Optimize the Ad Schedule ## Purpose Accounts routinely pay full price for 3 a.m. clicks that never convert while the budget runs dry before the evening window that does. This skill turns hour-of-week performance into a concrete schedule: reliable slots classified by real deviation math, adjustments only where the data can carry them, and a hard fork between Manual CPC (full adjustment range) and Smart Bidding (pause-only) so no effort is wasted on percentages the algorithm discards. ## When to run - 30+ days of data and suspected time-of-day or day-of-week waste. - Slot-level CPA/ROAS deviates 30%+ from the campaign average. - Budget-constrained campaign that exhausts spend before its historically best hours. - Quarterly schedule refresh, or after a bid-strategy/targeting change invalidated the old one. ## When NOT to run - Devices, locations, audiences, and demographics need the same treatment in one pass -> optimize-bid-modifiers (it includes the schedule dimension). - The campaign is in a Smart Bidding learning period -> wait; schedule edits during learning reset the clock (monitor-and-maintain-bid-strategy-health tracks status). - Under ~30 days of data or a handful of clicks per hour, noise, not signal; revisit later. - The real problem is total budget, not its timing -> allocate-budget-across-campaigns or handle-budget-limited-campaigns. ## Prerequisites - 30-60 days of stable campaign data with working conversion tracking. - Bid strategy type known (this forks the whole procedure). - Target CPA/ROAS for the campaign (adjustment math is anchored to it). - The account's conversion-lag figure, so the trailing incomplete days can be excluded from every matrix pull. ## Procedure 1. **Session guardrail.** Call `gads_policy_guardrail` before the session's first write. 2. **Gate on strategy type.** Read the campaign's strategy (via `gads_run_gaql_query` on `campaign.bidding_strategy_type`). Manual CPC -> full adjustment toolbox. Any Smart Bidding strategy -> the ONLY respected schedule action is -100% (pause a window); plan nothing else. 3. **Export the time matrix.** Pull 30-60 days (excluding trailing conversion-lag days) via `gads_get_ad_schedule_performance` and `gads_run_gaql_query` segmented by `segments.hour` and `segments.day_of_week`: clicks, cost, conversions, conversion rate, CPA (lead gen) or ROAS (ecommerce) per slot. Arrange as 24 hours x 7 days. 4. **Check data density.** 50+ clicks per slot -> trustworthy. 20-49 -> merge adjacent hours into blocks before judging. <20 -> merge into 3-4 hour blocks (morning / midday / afternoon / evening). Never rate a slot on single-digit clicks. 5. **Check consistency.** Split the range into individual weeks (GAQL with `segments.date` or `segments.week`) and confirm the same slots look good/bad across 4+ weeks. A slot that flips week to week is noise, leave it alone. 6. **Classify slots.** Deviation = (slot CPA - campaign average CPA) / campaign average CPA (invert the reading for ROAS). Then: >=30% cheaper than average -> strong window; within 30% -> neutral; 30-60% more expensive -> weak window; >=60% more expensive, or meaningful spend with zero conversions across the whole period -> dead window. Vertical priors (ecommerce evenings, B2B business hours) are hypotheses only, the matrix outranks them. 7. **Compute adjustments (Manual CPC only).** Per actionable slot: adjustment = (target CPA / slot CPA - 1) x 100. Practical bands: strong windows +40-50%; neutral 0%; weak -20% to -30%; very weak -50% to -70%; dead -100%. Remember schedule adjustments multiply with device/location modifiers (a +20% schedule on a +30% device is +56% combined), check the stack before applying. 8. **Design the slot layout.** At most 6 slots per day, 15-minute granularity, no overlaps, and any hour not covered by a slot does not serve. Merge adjacent same-class hours into single slots to stay under the limit. 9. **Apply (write).** Create the slots with `gads_add_ad_schedule`, then set per-slot modifiers with `gads_set_bid_adjustments`. Smart Bidding campaigns: create slots covering serving hours and apply -100% only to confirmed dead windows, no other percentages. Preview everything (validate_only=true default) as a slot->adjustment table; apply only after user approval. 10. **Validate.** Wait per volume: 100+ conversions/week -> 2 weeks; 25-99 -> 3 weeks; <25 -> 4 weeks. Re-pull the matrix via `gads_get_ad_schedule_performance` and compare totals (conversions, cost, CPA/ROAS, conversion rate, impression share) to the pre-change baseline. Watch for over-restriction: conversions down 20%+ -> reactivate marginal slots; IS falling in peak hours -> widen windows; CPA flat -> the schedule was not the constraint, consider reverting to always-on. 11. **Maintain.** Monthly spot-check; quarterly full re-analysis (steps 3-6), time patterns shift with seasons; re-test paused windows quarterly rather than assuming they stay dead. ## Decision rules - **Smart Bidding fork:** the algorithm already time-adjusts internally; percentage schedule modifiers are ignored. Only -100% acts. Pause a window only when it has zero conversions on meaningful spend over 30+ days, consistent across weeks. - **Density gates:** 50+ clicks/slot to act on individual hours; below that, merge into blocks. - **Consistency gate:** the pattern must repeat across 4+ weeks; never act on one week. - **Deviation bands:** +/-30% around the average is noise-tolerant neutral; act outside it, in proportion (step 7 bands). - **Allowed range:** schedule modifiers span -90% to +900%, plus -100% as a pause; multiplicative stacking with other dimensions. - **Business hours are not conversion hours.** Schedule from the matrix, not the office calendar, assisted research often happens evenings/weekends even in B2B. - **Conservative first pass:** pause only clear dead windows initially; tighten weak windows on the second cycle once the first change validates. ## Common failure modes - **Percentage adjustments on Smart Bidding.** They silently do nothing; the account looks managed while being unmanaged. The step 2 gate prevents it. - **Acting on thin slots.** A 12-click hour with one lucky conversion becomes a +50% modifier; density gates exist for this. - **Over-pausing.** Cutting every below-average hour shrinks reach until the campaign cannot spend; competitors inherit the vacated auctions. Pause dead, trim weak, keep neutral. - **Uncovered hours.** Forgetting that hours outside defined slots do not serve at all, an accidental blackout that looks like a delivery bug. - **Stacked inflation.** Schedule x device x location modifiers multiply; three positive modifiers can quietly double a bid. Compute the product before approving. - **Set-and-forget schedules.** Seasonal behavior shifts strand last quarter's schedule; the quarterly re-analysis is part of the skill, not optional. ## Related skills - Before: calculate-bid-targets (the target anchoring adjustment math), monitor-and-maintain-bid-strategy-health (confirm the strategy is stable, not learning). - Broader sibling: optimize-bid-modifiers (device/location/audience/demographic dimensions, same math and caps). - After: handle-budget-limited-campaigns (if budget still exhausts early even on the optimized schedule), run-a-weekly-performance-review (folds slot checks into routine monitoring).