Yandex Direct

<!-- versions:start -->

Version Requirements

Primary pins:

• Yandex Direct API: v5 (stable, JSON over HTTPS; api.direct.yandex.com/json/v5/{service})
• Sandbox: api-sandbox.direct.yandex.com/json/v5/{service}
• Python: 3.14.x
• Node.js: 24.x (Active LTS)

Verify against current Yandex Direct release notes before production use.

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. Read the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Programmatic campaign management in Yandex.Direct: create, update, suspend, archive via CampaignsService
• Bulk bid updates and strategy switching via BidsService / KeywordBidsService
• Loading keywords with negatives and operators via KeywordsService; tracking Status / State transitions (DRAFT/MODERATION/ACCEPTED/REJECTED)
• Creating and moderating ads (AdsService): TextAd, DynamicTextAd, MobileAppAd, ImageAd, CpcVideoAd, SmartAdBuilderAd
• Pulling statistics through the Reports API (TSV) with processingMode (online/offline/auto), 201/202 polling honoring Retry-After
• Working from an agency account: passing Client-Login per client, spending agency units via Use-Operator-Units: true
• Testing integration in the sandbox at api-sandbox.direct.yandex.com without burning real budgets
• Building your own client / connector (Python httpx, Node.js fetch) with units accounting, retry on 5xx/transient codes, manual idempotency
• Integrating into CRM/dashboard: pull account structure, adjust CPC from conversion signals, sync negative keywords

Do not use this skill when

• Web traffic analytics and goals from the site → yandex-metrica (cascade marker)
• SERP scraping, position tracking, snippet parsing → xmlstock (cascade marker)
• Wordstat frequency and keyword competition → mutagen (cascade marker)
• Google Ads / Google Ads API (different platform, different auction model) → google-ads cascade
• myTarget / VK Ads / VKontakte advertising → vk-ads / mytarget cascade
• Static on-site ad blocks, direct sales without auction
• Plain stats viewing through UI — Direct API is only needed for automation and scale

Purpose

Yandex.Direct API v5 is the official programmatic interface to Yandex's paid search and display platform. It manages campaigns (Search / Network / Master of Campaigns / Unified Performance / Dynamic / Smart banners / Mobile app / CPC Video / CPM Banner), ad groups, ads of all types, keywords and targetings, bids (manual and auto-strategies), reports (TSV), dictionaries, budget forecasts, and XML import/export.

This skill is high-stakes because:

1. Every write call spends real budget. AdsService.add and BidsService.set start serving and consume client money. A misplaced zero in MaxCpc = hundreds of thousands of rubles burned in an hour. Every write requires a sandbox dry-run plus explicit confirmation of magnitudes.
2. Units economy. Each method costs units from a per-account daily limit. Overrun → error 153 (UnitsLimitExceeded) and the batch ends up in an inconsistent state. Estimate cost before each batch; parse Units: consumed/remaining/daily-limit from every response.
3. Client-Login is mandatory for agencies. Forget it and the call runs against the agency's own account instead of the client's → auth error or, worse, silent change to the wrong account. Enforce in middleware and assert on Units-Used-Login in responses.
4. Partial errors in batch operations. AddResults / UpdateResults may contain a mix of Id and Errors per item. A 200 OK does not mean the batch fully succeeded — iterate per element.
5. Reports API has its own lifecycle. processingMode=offline returns HTTP 201 (queued) or 202 (forming); polling must respect Retry-After. Ignoring it → 429 / IP or account throttling. Maximum 5 parallel reports.
6. Sandbox ≠ production data. Sandbox campaigns are not shown to real users; stats are synthetic. Sandbox is still the right place to validate request structure and error handling without spending money.
7. No built-in idempotency. Repeating add with the same body creates a duplicate. Maintain client-side dedup by business key (name + parent id) or a unique external index on returned Id.
8. Token revocation. OAuth tokens can be revoked by the user — every request then fails with error_code 1002 / 506. Refresh logic and an "auth degraded" sentinel are required.
9. 10 000 IDs per selection. SelectionCriteria.Ids accepts up to 10 000; more → error 17. Chunk client-side.
10. suspend ≠ archive. Suspend pauses (reversible); archive is terminal and locks editing. Confusing them = losing the ability to mutate the object.

This skill owns Direct-domain knowledge: endpoints, headers, units economy, Reports lifecycle, agency access modeling, error semantics, sandbox testing. HTTP plumbing lives in httpx / nodejs; storage in postgresql.

Capabilities

OAuth 2.0 and Client-Login for agencies

Yandex Direct requires a Yandex ID OAuth token per user (advertiser or agency). Tokens are issued via the standard OAuth flow on oauth.yandex.ru or a manual debug token from the app page. For agencies: one token per agency + the Client-Login: <client-login> header selects the target account. Use-Operator-Units: true charges the agency's units rather than the client's. Without Client-Login, an agency token operates only on the agency account itself.

Full reference: references/setup.md

JSON envelope and required headers

Body is JSON: {"method": "<action>", "params": {...}}. Endpoint: POST https://api.direct.yandex.com/json/v5/<service> (or the sandbox host). Required headers: Authorization: Bearer <token>, Client-Login (agencies), Content-Type: application/json; charset=utf-8. Optional: Accept-Language: ru|en (message language), Use-Operator-Units: true, Accept-Encoding: gzip. Response headers: RequestId (for support), Units: <consumed>/<remaining>/<daily-limit>, Units-Used-Login (which account paid). Accept-Encoding: gzip is critical for large get responses and TSV reports.

Full reference: references/envelope-and-headers.md

Campaign and ad-group lifecycle — states, archive, suspend/resume

CampaignsService exposes get, add, update, delete, suspend, resume, archive, unarchive. Status (DRAFT, MODERATION, ACCEPTED, REJECTED) is moderation state; State (CONVERTED, ARCHIVED, SUSPENDED, ENDED, OFF, ON) is operational state. Types: TEXT_CAMPAIGN, UNIFIED_CAMPAIGN, DYNAMIC_TEXT_CAMPAIGN, MOBILE_APP_CAMPAIGN, CPM_BANNER_CAMPAIGN, SMART_CAMPAIGN, CPM_VIDEO_CAMPAIGN. AdGroupsService: get/add/update/delete with RegionIds, NegativeKeywords, TrackingParams. Prefer archive over delete for objects with stats.

Full reference: references/campaigns-and-adgroups.md

Ads and keywords — moderation and states

AdsService: get, add, update, delete, archive, unarchive, moderate, resume, suspend. Ad types live under exactly one of TextAd, MobileAppAd, DynamicTextAd, ImageAd, CpcVideoAdBuilderAd, SmartAdBuilderAd, CpmBannerAdBuilderAd. After add an ad is Status=DRAFT — moderate pushes it to MODERATION → ACCEPTED / REJECTED / PREACCEPTED. KeywordsService: get/add/update/delete/resume/suspend. Negative keywords apply at Campaign (NegativeKeywords), AdGroup, and Keyword level. Operators: !, +, [], "", -, (a|b).

Full reference: references/ads-and-keywords.md

Bids — manual, auto-strategies, search vs network split

BidsService: set, get, setAuto. KeywordBidsService is the current entry point for per-keyword bids. Auto-strategies: WB_MAXIMUM_CLICKS, WB_MAXIMUM_CONVERSION_RATE, AVERAGE_CPC, AVERAGE_CPA, WEEKLY_CLICK_PACKAGE, AVERAGE_ROI, PAY_FOR_CONVERSION, HIGHEST_POSITION, SERVING_OFF. Manual bids: SearchBid (search), NetworkBid (Network / RSYA), ContextCoverage (% of network reach). BidModifiersService adjusts by audience, geo, demographics, devices, time. All money fields are in micro-currency (divide by 1 000 000 for rubles).

Full reference: references/bids.md

Reports API — TSV lifecycle with polling

Dedicated endpoint: POST /json/v5/reports. Body: {"params": {"SelectionCriteria": {...}, "FieldNames": [...], "ReportName": "...", "ReportType": "CAMPAIGN_PERFORMANCE_REPORT|AD_PERFORMANCE_REPORT|...", "DateRangeType": "LAST_WEEK|CUSTOM_DATE|...", "Format": "TSV", "IncludeVAT": "YES|NO"}}. The processingMode header chooses online (sync up to 5 minutes), offline (queued, HTTP 201/202 + Retry-After), or auto. Set returnMoneyInMicros: false for rubles; skipReportHeader / skipColumnHeader / skipReportSummary: true for clean parsing. Polling: on 201/202, sleep Retry-After, repeat the identical POST until 200/error. Maximum 5 parallel reports.

Full reference: references/stats-tsv.md

Error codes — billing semantics, retry, partial errors

Common codes: 1 (InternalError), 2 (InvalidArgument), 8 (Forbidden), 9 (NotAllowedYet), 12 (ServiceTemporarilyUnavailable → retry), 17 (BadRequest), 52 (NoRights), 53 (AuthenticationError), 54 (InvalidLogin), 56 (NotFound), 58 (LimitReached), 152 (PreconditionFailed), 153 (UnitsLimitExceeded), 506 (TokenRevoked), 1000–1003 (auth-domain), 5000–9999 (service-specific). Partial errors in batches: HTTP 200 but result.AddResults[i].Errors[] per item. Warnings[] are non-blocking but must be logged.

Full reference: references/errors.md

Units economy — what costs what

Each method consumes units from a per-account daily limit. New apps start around 3 000–5 000 units/day; the limit grows with sustained usage. get is cheap (~1–40 units); add / update / delete is more expensive (~10–30 per call plus per-element cost). Reports enqueue costs ~10–20 units; polling and final download are free. Sandbox units are a separate wallet. Read the Units header after every response; throttle writes when remaining / daily_limit < 0.2.

Full reference: references/limits-and-units.md

Sandbox vs production

Sandbox host: api-sandbox.direct.yandex.com. Same OAuth token (Yandex ID is unified) but a separated, isolated tier. No UI — API only. Data is deleted after 1 month of inactivity. Reports in sandbox: one campaign per report; stats are synthetic. Use it for: request/response shape validation, error-path drills, polling behavior. Production-only checks: real moderation, real spend, bid adjustments against live audiences.

Full reference: references/setup.md

End-to-end workflow (bootstrap → ETL)

Bootstrap OAuth → sandbox smoke → JSON envelope → Campaigns lifecycle → AdGroups / Ads / Keywords flow → Bids (manual / auto) → Reports submit + poll + persist → idempotent daily ETL.

Full reference: references/workflow.md

Cookbook — 28 ready-to-use recipes

Auth, campaigns, ad groups, ads, keywords, bids, reports polling lifecycle, wordstat via Direct, agency clients, error handling, and migration from v0.4 (wordstat_keywords replacement).

Full reference: references/cookbook.md

Quick reference

Services

HTTP headers

Response headers