Manage Yandex Direct campaigns, ads, keywords, bids, reports via API v5. Use when the user needs to work with Yandex Direct API — campaign management, ad groups, ads, keywords, bids, targeting, reports, statistics, dictionaries, or any other Yandex Direct API operation. Triggers: Yandex Direct, Direct API, campaigns API, ad management API, keyword bids, Yandex advertising API, Direct reports, Direct statistics.
| 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 |
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:
direct:api permissionhttps://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID#access_token=TOKEN&token_type=bearer&expires_in=31536000Quick token setup:
bash scripts/get_token.sh --client-id YOUR_CLIENT_ID
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 responsePage -- pagination: Limit (max 10000) and Offsetadd methods use an array of objects (e.g., "Campaigns": [...])update methods use an array of objects with Id fielddelete methods use SelectionCriteria with Ids array{
"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"
}
}
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 |
| 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 |
YANDEX_DIRECT_SANDBOX=true in config or set base URL to api-sandbox.direct.yandex.comThe 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
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.
Verify API token and list available campaigns.
bash scripts/check_connection.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) |
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) |
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
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
Get reference data (regions, currencies, etc.).
bash scripts/dictionaries.sh --dict GeoRegions
bash scripts/dictionaries.sh --dict Currencies
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":{...}}')
| 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) |
Read the reference file matching the area you need:
bash scripts/check_connection.shPage.Limit and Page.Offset for paginating through large result sets (max 10000 per request)FieldNames you actually need to save API pointsChanges service to detect modifications before re-downloading all dataprocessingMode: auto and handle both 200 (ready) and 201/202 (pending) HTTP status codesreturnMoneyInMicros: false in report headers to get human-readable monetary valuesClient-Login headerapi-sandbox.direct.yandex.com) for development and testingconfig/.env (file is gitignored)returnMoneyInMicros: false header to get human-readable values, or divide by 1,000,000