Where things stand: which credentials are configured, what this server knows and when it was measured, and what it will not do. Call this first in a session — it says what is possible before anything is attempted.

Call any reading method of the Direct API v501 — campaigns.get, ads.get, keywords.get and so on — and get the result. Refuses anything that changes state: those go through direct_plan and direct_apply.

Cost in API units is checked before the call, not read from a header afterwards. Read knowledge://traps first: several read methods return an empty-looking answer unless the right field names are asked for, which looks like 'nothing was saved'.

Easy to miss: keywordsresearch.hassearchvolume answers whether a phrase has search demand (a boolean, not a figure), and dictionaries.get returns the reference books — regions and minimum bids among them.

Turn a list of intended API calls into a plan and return its identifier. Nothing is sent. The plan lists what would run and what it would cost in units.

Use this for every change. direct_apply accepts only an identifier and has no parameter for a request body, so the change that was read is the change that runs.

A plan that writes must also carry 'verify' — reading calls to run afterwards. This API reports success and sometimes does something else; without a read-back the outcome is unknown.

Perform the calls of a plan made earlier. Takes the plan identifier and a confirmation phrase — and nothing else.

This changes a live advertising account: Direct's sandbox is off unless switched on in the account, so a first write is real. There is no transaction, so a failure halfway leaves a partial state, and the tool says so.

It cannot start ads or unarchive: those methods are absent from this server.

Ask for a report and get its rows. Reports cost no API units, which makes them always cheaper than rebuilding the same numbers from object calls.

🔴 The period is checked before the request. Yandex keeps about three years of statistics and the boundary slides forward on the first of every month — and a request reaching past it does NOT fail. It returns the part that still exists, labelled with the dates you asked for, and nothing says it was cut. This tool refuses instead, and names the boundary.

Dates are explicit rather than relative, so the same request means the same thing tomorrow.

Attach local images or videos to an existing ad, doing the whole chain rather than one call.

A video takes three steps: uploading it puts it in the media library and nothing else, a creative has to be made from it, and only then can it go on the ad. Every step reports success on its own, which is why this is one tool.

Updating an ad also means resending its headlines and texts unchanged — the account requires them even when only a video changes, although the documentation does not say so. This tool reads the ad first and does that for you, and it never sends the legacy field that would collapse the ad to a single headline.

It reads the ad back afterwards and shows the headline count.

Frequency of search phrases from the Wordstat API (Yandex Search API v2, Yandex Cloud — not the Direct API). Methods: 'top' — a phrase's frequency plus phrases containing it; 'dynamics' — demand over time; 'regions' — distribution across the world; 'tree' — the region code tree.

🔴 A call spends REAL MONEY from the cloud folder, not Direct API units: top and dynamics ~0.02 rubles each, regions ~0.05. 'tree' is FREE — start with it, both to take region codes from and to prove the credential works at no cost. The real bottleneck is the quota of 100 calls per sliding hour; it is seized locally BEFORE the network, and an exhausted quota is refused with the wait named.

Needs its own credential — a Yandex Cloud Api-Key and folder id: python -m shturman_direct login searchapi.

The Yandex Metrika API, reading only. Three actions: 'counters' lists the counters this token can see; 'goals' lists one counter's goals; 'stat' answers one statistics slice — dimensions and metrics travel to the API as the ym:* names you write, and accuracy=full is sewn in because the service default is SAMPLING, on which a rare conversion rounds to zero while the report looks ordinary.

🔴 Data arrives with a lag of about 2 hours: the current day is underfilled, and judging it has produced wrong conclusions twice in a row. End the window yesterday.

Needs its own credential, not the Direct one: python -m shturman_direct login metrika. Creating goals is a write and lives in direct_metrika_goals.

Create JavaScript-event goals in one Metrika counter, idempotently: what the counter already has is checked by the event identifier first, only the missing goals are created, and the existing ones are never changed and never deleted. After creating, the counter is read back — a goal the read-back does not show is an error, not a footnote.

🔴 Goals must exist BEFORE the first ad click: retroactive credit does not exist in Metrika, and a duplicate goal is worse than a missing one — an autostrategy learns on doubled counts.

Called without a confirmation it answers a preview: ✓ already exists / + will be created. The confirmation phrase names the counter, so a write aimed at the wrong counter is caught at the moment of confirming.

The Yandex Audience API, reading only. Two actions: 'segments' lists the segments of the token's login — each with its owner and status (is_processed while counting, processed when ready); 'stat' answers one segment's reach and affinity — totals lives HERE, not in the segment object, and no_data=true means the segment is still counting, so its zero measures nothing.

🔴 Direct sees ONLY processed segments, and under a DIFFERENT number than the Audience id — a retargeting condition is verified by reading retargetinglists, never by computing (knowledge://audience).

Needs its own credential — a token of your own application with the two Audience checkboxes; no access request exists for this API: python -m shturman_direct login audience. Creating segments is a write and lives in direct_audience_segments.

Create ONE geo segment in Yandex Audience from CIRCLES — the one create path measured live. Polygons are recorded as knowledge only (knowledge://audience) and deliberately not implemented: their shape was never probed against the live service.

Radius is METERS, 500..10000 — the unit is proven by a two-sided probe; kilometers here would draw 500 km circles. A segment holds up to 1000 points, a 'condition' segment up to 100 (a limit bought by a live refusal), and 'condition' requires both period_length and times_quantity. Everything checkable is checked BEFORE the network, because the service's wrapper refusal masks every other complaint.

Called without a confirmation it answers a preview. After creating, the list is read back with the status — Direct sees the segment only after processed, and under a DIFFERENT number: verify by reading retargetinglists.