List ad groups (VK Ads ad_group objects) in the connected cabinet.

Ad groups live inside campaigns (ad_plan objects) and contain the individual banners (creatives). This read-only tool drains every page of the /ad_groups.json listing endpoint and returns the RAW item dicts so every requested field reaches you for analysis.

By default the API returns a MINIMAL field set. Pass fields to get rich data, e.g. "id,name,status,targetings,utm,banners,package_id". The targetings field exposes age/gender/geo/interests. Call the describe_fields tool with resource="ad_groups" first to learn the full set of valid field names.

List banners (creatives) in the own VK Ads cabinet.

Fetches every banner from GET /banners.json, transparently paginating over all result pages, and returns the RAW item dicts so every requested field reaches you for analysis. Read-only.

By default the API returns a MINIMAL field set. Pass fields to get rich creative data, e.g. "id,status,content,textblocks,urls,moderation_status". The content field carries the creative variants/urls. Call the describe_fields tool with resource="banners" first to learn the full set of valid field names.

List ad campaigns (VK Ads ad_plans) for the authenticated cabinet.

Fetches every campaign from GET /ad_plans.json, transparently walking the offset-based pagination, and returns the RAW item dicts so every field you request reaches you for analysis.

By default the API returns a MINIMAL field set. To get rich data pass fields with the columns you need, e.g. "id,name,status,objective,budget_limit,budget_limit_day,autobidding_mode," "max_price,priced_goal,delivery,efficiency_status,date_start,date_end". Call the describe_fields tool with resource="ad_plans" first to learn the full set of valid field names for this resource.

Discover which fields a VK Ads resource accepts. Call this FIRST.

Call this before the list tools to learn which fields you can request, then pass the ones you need as the fields argument of list_campaigns, list_ad_groups or list_banners. The valid set is discovered live against the cabinet, so it always reflects the real API.

How it works: the tool sends a request carrying one deliberately-invalid field. The API rejects it with HTTP 400 and a body listing every allowed field, which this tool parses and returns.

Export VK Ads statistics to a CSV file on disk.

Fetches statistics for the given object type and date range via the shared client (which transparently splits ranges longer than 92 days and id lists longer than 50 into multiple requests), flattens each returned item into a CSV row using the stdlib :mod:csv module, and writes the result to output_path. Read-only: it never mutates any ad object.

The CSV header is the union of every key seen across all items, in first-seen order. Missing values for a given row are written as empty cells. All values are stringified.

Rank VK Ads objects by a performance metric and return the top N.

Fetches statistics via the shared client, reads the chosen metric from each object's total.base aggregate, sorts the objects, and returns the best (or worst) limit of them. Use this to pick the best-performing (or worst-performing) campaigns, ad groups or banners.

Fetch performance statistics for VK Ads objects.

Retrieves statistics from GET /statistics/{object_type}/{period}.json and returns a merged {"items": [...]} payload. The underlying client transparently handles the API's hard limits: date ranges longer than 92 days are split into multiple inclusive windows, and id lists longer than 50 are chunked, with all responses merged into a single result. The caller never has to worry about those limits.

Report remaining VK Ads API quota for diagnostics.

Combines two sources of throttling information:

• A live GET /throttling.json call returning the API's current view of remaining requests per second, per hour, and per day (throttling).

• The last X-RateLimit-* header values observed on any prior request, cached on the shared client (last_seen).

Use this to check how much API budget is left before issuing further listing or statistics requests, or to debug HTTP 429 rate-limit errors.

Returns: A dict with two keys:

* ``throttling``: the decoded ``/throttling.json`` body (remaining and
  limit values for rps/hourly/daily quotas, as returned by the API).
* ``last_seen``: the most recent rate-limit header values observed by
  the client (``rps_remaining``, ``hourly_remaining``,
  ``daily_remaining``); values are ``None`` until a request has run.