direct

# Yandex Direct — PPC Audit & Management (API v5) **Authors:** Nick Serebrov & Kobe 🐍 Full-cycle Yandex Direct management: account audits, campaign CRUD, keyword management, reporting, optimization, and budget analysis. ## Quick Reference | Command | What it does | |---------|-------------| | `/direct audit` | Full account audit (all campaigns), scoring 0-100 | | `/direct campaigns` | List campaigns with statuses and key metrics | | `/direct create` | Create campaign (Search/YAN) with ad groups, keywords, ads | | `/direct keywords` | Keyword management (list, add, update bids, pause) | | `/direct report` | Performance stats (CTR, CPC, conversions, spend) | | `/direct optimize` | Optimization recommendations (pause losers, adjust bids) | | `/direct budget` | Budget spend analysis and forecasting | | `/direct negative` | Negative keyword management (campaign & shared sets) | ## API Configuration Credentials: `~/.secrets/yandex-direct.json` ```json { "client_id": "...", "client_secret": "...", "oauth_token": "..." } ``` Endpoint: `https://api.direct.yandex.com/json/v5/` Auth: `Authorization: Bearer {oauth_token}` API wrapper script: `scripts/yd-api.sh` ## Orchestration Logic ### `/direct audit` 1. Load credentials from `~/.secrets/yandex-direct.json` 2. Fetch all campaigns via API (`campaigns` service) 3. Fetch ad groups, keywords, ads, sitelinks for each campaign 4. Run 50+ checks from `references/yandex-audit.md` 5. Score using `references/scoring-system.md` 6. Compare metrics against `references/benchmarks.md` 7. Generate report with grade (A-F), findings, and prioritized action plan ### `/direct campaigns` 1. Call `campaigns.get` with fields: Id, Name, Status, State, Statistics, DailyBudget, Strategy 2. Format table with status indicators 3. Show key metrics if available (impressions, clicks, spend) ### `/direct create` 1. Gather: campaign name, type (SEARCH/YAN), geo, budget, strategy 2. Create campaign via `campaigns.add` 3. Create ad groups via `adgroups.add` 4. Add keywords via `keywords.add` 5. Create ads via `ads.add` (TextAd for search, TextImageAd for YAN) 6. Add sitelinks and callouts ### `/direct keywords` 1. Fetch keywords via `keywords.get` with campaign/adgroup filter 2. Operations: add, suspend, resume, update bids, delete 3. Show quality metrics where available ### `/direct report` 1. Use Reports service (`/json/v5/reports`) 2. Build TSV report request with selected fields 3. Available presets: campaign, adgroup, keyword, search_query 4. Date ranges: today, yesterday, last7, last30, custom 5. Parse and format results ### `/direct optimize` 1. Run report for last 30 days 2. Identify: zero-conversion keywords (spend > 2x avg CPA), low CTR ads, expensive placements 3. Cross-reference with `references/benchmarks.md` 4. Generate recommendations sorted by impact 5. Apply 3x Kill Rule: flag anything with CPA > 3x target ### `/direct budget` 1. Fetch campaign budgets and daily spend 2. Calculate run rate, projected monthly spend 3. Flag underspending (< 70% of budget) and overspending campaigns 4. Budget sufficiency check vs strategy requirements ### `/direct negative` 1. Fetch negative keywords at campaign and ad group level 2. Fetch shared negative keyword sets (`negativekeywordsharedsets`) 3. Analyze search query report for new negatives 4. Add/remove negatives via API ## Quality Gates - Never recommend broad match keywords without auto-strategy (Yandex best practice) - 3x Kill Rule: flag keywords/groups with CPA > 3x target for pause - Budget sufficiency: daily budget should support ≥10 clicks at current CPC - Moderation: always check ad moderation status before optimizing - Learning phase: don't change strategy settings during first 7 days - UTM: all ads must have UTM parameters for Metrika attribution ## Reference Files Load on-demand, NOT at startup: - `references/yandex-audit.md` — 50+ audit checks (YD01-YD55) - `references/scoring-system.md` — Weighted scoring (0-100, grades A-F) - `references/benchmarks.md` — Russian market benchmarks (CTR, CPC, CVR) - `references/bidding-strategies.md` — Yandex Direct bidding strategy guide - `references/compliance.md` — Yandex moderation rules & ad policies - `references/image-specs.md` — Image sizes and specs for YAN (RSY) ads ## Scripts - `scripts/yd-api.sh` — Generic API v5 call wrapper - `scripts/yd-report.sh` — Reports service wrapper - `scripts/yd-audit.sh` — Automated audit data collection ## Subagents - `agents/audit-yandex.md` — Audit subagent for parallel campaign analysis