Track spend and conversions across Yandex Direct campaigns

The agent works with version five of the Direct API at https://api.direct.yandex.com/json/v5: campaigns, ad groups, ads, keywords and autotargetings with their bids, negative keywords, portfolio strategies, bid adjustments, region reference books and reports. Out of that it assembles spend, impressions, clicks, CTR and conversions for a period, goes down from the campaign level to an individual keyword and on to the actual search query, and finds what burns budget without bringing in a single conversion.

An enabled campaign in Direct does not mean a running one: state and status are different things here, and a campaign can be stalled by rejected moderation, an exhausted daily budget or an empty account while still being «enabled». The agent reads both fields together with the payment status and names the real reason for the stop. Statistics for the current day are still being written in, so it builds comparisons on closed days and always names the period the figures were taken for.

The unified performance campaign lives at its own API address, and the former dynamic campaigns and smart banners have been migrated into it and are no longer created anew. The agent reads such campaigns where they actually sit rather than reporting «nothing found» for advertising that exists. Autotargeting is shown next to keywords: in a unified campaign it is on by default, and spend without a single keyword is usually exactly that.

The agent can change bids and pause campaigns if the login has edit rights: permissions carry over from the web interface one to one, and with read-only access you still get the analytics. But a bid is money in real time, so the agent first shows the current value, the proposed one and the number of keywords affected, waits for confirmation and re-reads the result after applying it — Direct answers «success» even for a batch in which some rows were rejected.

The connection is made by confirming a code on a Yandex page — there are no tokens to copy, and access is renewed on its own afterwards. Direct counts Units against a daily quota: every request costs points and a failed one costs twenty, so the agent asks only for the fields it needs and does not hammer the API with the same broken body. No more than five requests run in parallel, so it paginates through selections, orders heavy reports in offline mode and waits until they are ready, and states any shortage of data or permissions directly.