Yandex Direct API v5

Essentials

Base URLs

| Environment | JSON Endpoint | SOAP Endpoint | |-------------|--------------|---------------| | Production | https://api.direct.yandex.com/json/v5/{service} | https://api.direct.yandex.com/v5/{service} | | Sandbox | https://api-sandbox.direct.yandex.com/json/v5/{service} | https://api-sandbox.direct.yandex.com/v5/{service} | | Reports | https://api.direct.yandex.com/json/v5/reports | Same pattern | | Reports (sandbox) | https://api-sandbox.direct.yandex.com/json/v5/reports | Same pattern |

Authentication

All requests require an OAuth token in the Authorization header.

Required Headers (every request):

| Header | Value | Required | |--------|-------|----------| | Authorization | Bearer YOUR_OAUTH_TOKEN | Always | | Content-Type | application/json; charset=utf-8 | Always | | Accept-Language | ru or en | Recommended | | Client-Login | client_login | Agency accounts only |

Getting an OAuth Token:

1. Register app at https://oauth.yandex.ru/client/new with direct:api permission
2. Get token: https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID
3. Token appears in redirect URL: #access_token=TOKEN&token_type=bearer&expires_in=31536000
4. Token is valid for 1 year

Quick token setup:

bash scripts/get_token.sh --client-id YOUR_CLIENT_ID

Request Format (JSON)

Every API request (except Reports) follows this JSON structure:

{
  "method": "get|add|update|delete|suspend|resume|archive|unarchive|...",
  "params": {
    "SelectionCriteria": { ... },
    "FieldNames": ["Id", "Name", ...],
    "Page": { "Limit": 10000, "Offset": 0 }
  }
}

Key patterns:

• SelectionCriteria -- filter which objects to return (Ids, CampaignIds, States, Statuses, Types, etc.)
• FieldNames -- which fields to include in the response
• Page -- pagination: Limit (max 10000) and Offset
• add methods use an array of objects (e.g., "Campaigns": [...])
• update methods use an array of objects with Id field
• delete methods use SelectionCriteria with Ids array

Response Format

{
  "result": {
    "Campaigns": [ ... ],
    "LimitedBy": 10000
  }
}

• LimitedBy appears when there are more objects than returned (need pagination)

Error response:

{
  "error": {
    "error_code": 53,
    "error_string": "Authorization error",
    "error_detail": "Token not found or expired"
  }
}

Units (API Points) System

Every response includes the Units HTTP header: Units: spent/remaining/daily_limit

Example: Units: 10/20828/64000 means 10 points spent, 20828 remaining, 64000 daily limit.

| Rule | Detail | |------|--------| | Daily limit | Individual per advertiser, based on campaign activity | | Refresh | Points awarded every 60 minutes (sliding 24h window) | | Per period | 1/24 of daily limit per hour + unspent from previous 23 hours | | Concurrent requests | Max 5 simultaneous requests per advertiser | | Error cost | 20 points per error (except server errors) | | Minimum daily limit | ~64,000 points for active accounts | | Agency | Points deducted from advertiser by default; agency can opt to use own points |

Common Error Codes

| Code | Meaning | Action | |------|---------|--------| | 53 | Authorization error | Check token validity | | 152 | Insufficient points | Wait for points refresh (hourly) | | 1000 | Concurrent request limit | Reduce parallel requests | | 1001 | Operation limit exceeded | Reduce batch size | | 1002 | Invalid token | Reauthorize, get new token | | 2000 | Unknown error | Retry after delay | | 8800 | Object limit per request | Reduce batch size | | 9000 | Insufficient units | Wait for daily limit refresh |

Sandbox

• Completely isolated from production data
• No web interface -- API only
• Same restrictions as live API
• Reports limited to one campaign per request
• Data deleted after 1 month of inactivity
• Roles: Advertiser or Agency (with 3 test clients)
• Use YANDEX_DIRECT_SANDBOX=true in config or set base URL to api-sandbox.direct.yandex.com

Configuration

The skill uses config/.env for credentials:

# Required
YANDEX_DIRECT_TOKEN=your_oauth_token

# Optional: sandbox mode
YANDEX_DIRECT_SANDBOX=true

# Optional: agency client login
YANDEX_DIRECT_CLIENT_LOGIN=client_login

Scripts

IMPORTANT: Always run scripts with bash prefix and absolute paths from the skill directory. Scripts use bash-specific features and will not work if sourced from zsh. Do NOT source scripts/common.sh directly — use the wrapper scripts below.

check_connection.sh

Verify API token and list available campaigns.

bash scripts/check_connection.sh

campaigns.sh

Manage campaigns: list, get details, stats, suspend/resume/archive.

# List all campaigns
bash scripts/campaigns.sh --action list

# List only active campaigns
bash scripts/campaigns.sh --action list --states ON

# Get full campaign details
bash scripts/campaigns.sh --action get --ids 12345678

# Get campaign funds/spend info
bash scripts/campaigns.sh --action stats --ids 12345678

# Suspend a campaign
bash scripts/campaigns.sh --action suspend --ids 12345678

# Resume a campaign
bash scripts/campaigns.sh --action resume --ids 12345678

| Param | Description | |-------|-------------| | --action, -a | list, get, stats, suspend, resume, archive, unarchive | | --ids, -i | Comma-separated campaign IDs | | --states, -s | Filter: ON, OFF, SUSPENDED, ENDED, ARCHIVED | | --limit, -l | Max results (default: 100) |

ads.sh

Manage ads: list, get details, suspend/resume/moderate/archive.

# List ads by campaign
bash scripts/ads.sh --action list --campaign-ids 12345678

# List ads by ad group
bash scripts/ads.sh --action list --adgroup-ids 987654

# Get specific ad details
bash scripts/ads.sh --action get --ad-ids 111222333

# Suspend an ad
bash scripts/ads.sh --action suspend --ad-ids 111222333

| Param | Description | |-------|-------------| | --action, -a | list, get, suspend, resume, moderate, archive | | --campaign-ids | Filter by campaign IDs | | --adgroup-ids | Filter by ad group IDs | | --ad-ids | Specific ad IDs | | --limit, -l | Max results (default: 1000) |

keywords.sh

Manage keywords and autotargeting.

# List keywords by campaign
bash scripts/keywords.sh --action list --campaign-ids 12345678

# List keywords by ad group
bash scripts/keywords.sh --action list --adgroup-ids 987654

# Suspend keywords
bash scripts/keywords.sh --action suspend --ids 111,222,333

reports.sh

Pull statistics reports (campaign, ad group, ad, keyword level).

# Campaign performance (last 30 days)
bash scripts/reports.sh

# Campaign performance for custom date range
bash scripts/reports.sh --date-range CUSTOM_DATE --date-from 2026-01-01 --date-to 2026-01-31

# Ad-level performance
bash scripts/reports.sh --type AD_PERFORMANCE_REPORT \
  --fields "AdId,AdGroupId,Impressions,Clicks,Ctr,AvgCpc,Cost"

# Keyword/criteria performance with filter
bash scripts/reports.sh --type CRITERIA_PERFORMANCE_REPORT \
  --fields "CriteriaType,Criteria,Impressions,Clicks,Ctr,AvgCpc,Cost" \
  --filter '{"Field":"CampaignId","Operator":"EQUALS","Values":["12345678"]}'

# Demographics (age/gender)
bash scripts/reports.sh --type CAMPAIGN_PERFORMANCE_REPORT \
  --fields "Age,Gender,Impressions,Clicks,Ctr,Cost"

# Search queries report
bash scripts/reports.sh --type SEARCH_QUERY_PERFORMANCE_REPORT \
  --fields "Query,Impressions,Clicks,Ctr,Cost"

# Save report to file
bash scripts/reports.sh --output report.tsv

# Predefined date ranges
bash scripts/reports.sh --date-range YESTERDAY
bash scripts/reports.sh --date-range LAST_7_DAYS
bash scripts/reports.sh --date-range THIS_MONTH

| Param | Default | Description | |-------|---------|-------------| | --type, -t | CAMPAIGN_PERFORMANCE_REPORT | Report type (see below) | | --date-range, -r | LAST_30_DAYS | Date range preset | | --date-from | — | Start date for CUSTOM_DATE | | --date-to | — | End date for CUSTOM_DATE | | --fields, -f | CampaignName,Impressions,Clicks,Ctr,AvgCpc,Cost | Fields | | --filter | — | Filter JSON | | --output, -o | stdout | Save to file | | --name, -n | auto-generated | Report name |

Report types: ACCOUNT_PERFORMANCE_REPORT, CAMPAIGN_PERFORMANCE_REPORT, ADGROUP_PERFORMANCE_REPORT, AD_PERFORMANCE_REPORT, CRITERIA_PERFORMANCE_REPORT, SEARCH_QUERY_PERFORMANCE_REPORT, CUSTOM_REPORT

Date ranges: TODAY, YESTERDAY, LAST_3_DAYS, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_MONTH, LAST_MONTH, ALL_TIME, CUSTOM_DATE

dictionaries.sh

Get reference data (regions, currencies, etc.).

bash scripts/dictionaries.sh --dict GeoRegions
bash scripts/dictionaries.sh --dict Currencies

Advanced: common.sh functions

For custom API calls not covered by scripts above, use common.sh functions. Must be run inside a bash script (not sourced from zsh):

#!/bin/bash
source /path/to/scripts/common.sh
load_config
response=$(direct_request "campaigns" '{"method":"get","params":{...}}')

All API v5 Services

| Service | Endpoint Suffix | Methods | Purpose | |---------|----------------|---------|---------| | Campaigns | /campaigns | add, update, delete, get, suspend, resume, archive, unarchive | Campaign management | | AdGroups | /adgroups | add, update, delete, get | Ad group management | | Ads | /ads | add, update, delete, get, moderate, suspend, resume, archive, unarchive | Ad management | | Keywords | /keywords | add, update, delete, get, suspend, resume | Keyword/autotargeting management | | BidModifiers | /bidmodifiers | add, set, delete, get | Bid adjustment management | | KeywordBids | /keywordbids | set, setAuto, get | Keyword bid management | | AudienceTargets | /audiencetargets | add, delete, suspend, resume, get, setBids | Audience target management | | RetargetingLists | /retargetinglists | add, update, delete, get | Retargeting list management | | Sitelinks | /sitelinks | add, delete, get | Sitelink set management | | AdExtensions | /adextensions | add, delete, get | Callout extension management | | VCards | /vcards | add, delete, get | Virtual business card management | | AdImages | /adimages | add, delete, get | Image management | | AdVideos | /advideos | add, get | Video management | | Creatives | /creatives | add, get | Creative management | | Reports | /reports | POST (custom) | Statistics and reporting | | Dictionaries | /dictionaries | get | Reference data (regions, currencies, etc.) | | Clients | /clients | get, update | Advertiser account management | | AgencyClients | /agencyclients | add, update, get | Agency client management | | Changes | /changes | check, checkCampaigns, checkDictionaries | Change tracking | | Feeds | /feeds | add, update, delete, get | Product feed management | | DynamicTextAdTargets | /dynamictextadtargets | add, delete, get, resume, setBids, suspend | Dynamic ad targeting | | SmartAdTargets | /smartadtargets | add, update, delete, get, resume, setBids, suspend | Smart banner targeting | | TurboPages | /turbopages | get | Turbo page parameters | | Businesses | /businesses | get | Business profile data | | Strategies | /strategies | add, update, get, archive, unarchive | Portfolio strategy management | | NegativeKeywordSharedSets | /negativekeywordsharedsets | add, update, delete, get | Shared negative keyword sets | | KeywordsResearch | /keywordsresearch | hasSearchVolume, deduplicate | Keyword preprocessing | | Leads | /leads | get | Turbo page form submissions | | Bids | /bids | set, setAuto, get | Bid management (legacy) |

Detailed References

Read the reference file matching the area you need:

• Campaign Management (Campaigns, AdGroups, Ads, Keywords, BidModifiers, KeywordBids) -- references/campaigns.md
• Targeting (AudienceTargets, RetargetingLists, DynamicTextAdTargets, SmartAdTargets) -- references/targeting.md
• Extensions (Sitelinks, AdExtensions, VCards, AdImages, AdVideos, Creatives) -- references/extensions.md
• Reports (Report service, report types, field names, date ranges, filters, headers) -- references/reports.md
• Other Services (Dictionaries, Changes, Clients, AgencyClients, Feeds, Strategies, NegativeKeywordSharedSets, TurboPages, Businesses, Leads, KeywordsResearch) -- references/other-services.md
• Common Use Cases (bash script examples for frequent tasks) -- references/use-cases.md

Guidelines

• Always verify the token is valid before batch operations: bash scripts/check_connection.sh
• Use Page.Limit and Page.Offset for paginating through large result sets (max 10000 per request)
• Request only the FieldNames you actually need to save API points
• Use the Changes service to detect modifications before re-downloading all data
• For reports, use processingMode: auto and handle both 200 (ready) and 201/202 (pending) HTTP status codes
• Set returnMoneyInMicros: false in report headers to get human-readable monetary values
• For agency accounts, always include the Client-Login header
• Max 5 concurrent requests per advertiser -- queue or throttle your requests
• Use sandbox (api-sandbox.direct.yandex.com) for development and testing
• Store tokens securely in config/.env (file is gitignored)
• For monetary values in standard API requests/responses: amounts are in micros (multiplied by 1,000,000)
• For monetary values in reports: use returnMoneyInMicros: false header to get human-readable values, or divide by 1,000,000