/yandex-metrica

name: yandex-metrica
description: "[RU: яндекс метрика, метрика api, logs api, цели метрики] Yandex.Metrika API via api-metrika.yandex.net with OAuth 2.0. Reporting API v1 (/stat/v1/data, /bytime, /drilldown, /comparison) with ym:s:/ym:pv:/ym:u: namespaces, filter DSL, attribution models; Logs API raw hits/visits lifecycle created→processed→cleaned, 10 GB/counter; Management API for counters/goals/filters CRUD. Quotas: 5000 req/day per user_login, 30 req/s per IP (10 for Logs), 3 parallel, 200 req/5min. Use when: яндекс метрика, metrika api, /stat/v1/data, logs api, raw hits export, ym:s:visits, counter_id, attribution, цели метрики. SKIP: Webmaster (→yandex-webmaster); Direct ads (→yandex-direct); GA4 (→google-analytics); AppMetrica (→appmetrica); CRM (→amocrm/bitrix24)."
stacks:
  - yandex-metrica
  - ru-analytics
  - python
  - nodejs
tags:
  - analytics
  - ru
  - yandex
  - metrika
  - attribution
  - logs-api
  - oauth
source: vechkasov-global-skills
risk: high-stakes

<!-- versions:start -->

Version Requirements (May 2026)

**Primary pins:**

• Yandex Metrika API: `Reporting v1 (/stat/v1/data), Management v1 (/management/v1), Logs (/management/v1/counter/{id}/logrequests*) — stable, no deprecation notice`
• Base URL: `https://api-metrika.yandex.net`
• Python: `3.14.x`
• Node.js: `24.x (Active LTS)`

> Source of truth: [STACK_VERSIONS.md](../../STACK_VERSIONS.md) — verified 2026-08-24

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Pulling traffic/source/goal/conversion reports via Reporting API (`/stat/v1/data`)
• Time-series via `/stat/v1/data/bytime` (charts grouped by day/week/month)
• Hierarchical drill-down (e.g. city → page → device) via `/stat/v1/data/drilldown`
• A/B segment or period comparisons via `/stat/v1/data/comparison`
• Raw hit/visit export via Logs API for ClickHouse / BigQuery / DuckDB
• Multi-touch attribution — first/last/last-significant/Yandex Direct/cross-device via `attribution=`
• CRUD on counters, goals, filters, representatives, operations via Management API
• Importing expenses, CRM data, offline conversions, user params via Data Import API
• Storing OAuth tokens with the right minimum scope (`metrika:read` / `metrika:write` / `metrika:offline_data`)
• Building a Python (`httpx`) or Node.js client with Logs API polling, 429/503 retry, `request_id` deduplication
• Detecting sampling (`sampled=true`, `sample_share`) and re-running with `accuracy=full` when needed

Do not use this skill when

• Search Console-style queries / index / sitemap — that is **not** Metrika. Use `yandex-webmaster` (cascade marker)
• Yandex.Direct ad campaign stats (impressions, clicks, CPC, CTR) — separate API. Use `yandex-direct` (cascade marker)
• Google Analytics 4 — different platform and API. Use `google-analytics` (cascade marker)
• AppMetrica (mobile app analytics on appmetrica.yandex.com) — separate API. Use `appmetrica` (cascade marker)
• Placing the JS tag on a page or configuring goals via JS — that is tag-manager / frontend work, not API
• Downstream processing of collected data (ETL, ClickHouse, dashboards) — that belongs to `clickhouse` / `polars` / `pandas` / `postgresql`
• Session-recording (Webvisor) data — Webvisor API exists separately and is not covered here

Purpose

Yandex.Metrika is the largest Russian web-analytics platform (the GA4 equivalent for the RU market). The API exposes three surfaces: **Reporting API** (`/stat/v1/data*`) — aggregated reports with `dimensions`, `metrics`, filter-segments and attribution models; **Logs API** (`/management/v1/counter/{id}/logrequests*`) — raw hit/visit export in TSV with `created`→`processed`→`cleaned` lifecycle; **Management API** (`/management/v1`) — CRUD on counters, goals, filters, operations. All endpoints are OAuth-authenticated against `api-metrika.yandex.net`.

This skill is **high-stakes** because:

1. **Sampling kicks in silently.** Default `accuracy=medium` returns `sampled: true`, `sample_share: 0.05` (5% of data) for heavy queries. Decisions made on an unrepresentative sample are decisions made on noise. Mitigation: `accuracy=full` for finance-critical reports; always inspect `sampled` and `sample_share` in the response. 2. **5000 requests/day per `user_login`** — resets at 00:00 GMT (03:00 MSK). A dashboard polling every minute exhausts the budget before lunch. Cache responses, aggregate queries. 3. **200 requests / 5 minutes on `/stat/v1/data/`** — a separate counter from the daily cap. Tripping it blocks the endpoint for 5 minutes. 4. **3 parallel requests per user_login** — more than that → 429. Do not run N workers without a semaphore. 5. **30 req/s per IP** (10 req/s for Logs API) — exceeding returns 429 with `Retry-After`. 6. **Logs API: 10 GB per counter** total uncleaned prepared logs. Forget to clean → `400 quota_exceeded`. Always `POST .../clean` after a successful download. 7. **Logs API: 1-year max range** in a single request, and `fields` ≤ 3000 characters. Split larger ranges client-side. 8. **Attribution shifts numbers dramatically.** The same conversion under `LAST` vs `FIRST` attributes to different sources. The default is `LASTSIGN` (last significant). If API numbers disagree with the web UI, check the attribution model. 9. **`counter_id` (`ids=`) is mandatory and easy to mix up.** One token may have access to dozens of counters; passing the wrong one returns 403. 10. **OAuth scope: read vs write.** `metrika:read` covers Reporting and Logs API but **not** goal/filter creation or imports. Use `metrika:write` only when CRUD is required. 11. **Same-day data is unstable.** Metrika finalizes ~99% of sessions within 3 days. Requests for `today` are meaningless for final figures.

This skill owns the provider-domain knowledge: endpoints, dimension/metric namespaces, filter DSL, Logs API lifecycle,