Yandex Metrica

<!-- 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 — 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, quotas, attribution models, OAuth scopes. HTTP transport belongs to httpx / nodejs.

Capabilities

OAuth 2.0 and scopes

All requests require Authorization: OAuth <token> (the official scheme; Bearer <token> also works). Tokens are issued via oauth.yandex.ru — application type "For API access / debugging", client_id, Implicit-flow callback. Scopes: metrika:read (reports, Logs API, settings read), metrika:write (counters/goals/filters/operations CRUD), metrika:expenses / metrika:user_params / metrika:offline_data (imports; covered by metrika:write). For organization accounts add passport:business. Tokens have no default TTL but can be revoked by the user.

Full reference: references/setup.md

End-to-end API workflow

Bootstrap → list counters → standard reports → time-series / drilldown / comparison → Logs API submit→poll→download→clean → goals/filters CRUD → quotas & defensive backoff → daily ETL into Postgres.

Full reference: references/workflow.md

Reporting API — request structure

GET https://api-metrika.yandex.net/stat/v1/data?ids=<counter_id>&dimensions=<ym:...>&metrics=<ym:...>&date1=YYYY-MM-DD&date2=YYYY-MM-DD&filters=<expr>&sort=<field>&limit=<n>&offset=<n>&accuracy=full&attribution=LASTSIGN&group=day&direct_client_logins=.... Limits: up to 10 dimensions per request; default limit=100, max 100000 (paginate via offset); date1/date2 accept today, yesterday, NdaysAgo. Endpoints: /stat/v1/data (table), /stat/v1/data/bytime (series), /stat/v1/data/drilldown (hierarchy), /stat/v1/data/comparison (segment comparison).

Full reference: references/reporting-api.md

Dimensions and metrics — namespaces

Namespaces: ym:s: (sessions/visits — the workhorse), ym:pv: (page views), ym:u: (users), ym:up: (user params), ym:ad: (Yandex.Direct), ym:sp: (search phrases), ym:el: (external links), ym:dl: (downloads), ym:ev: (events). Dimensions and metrics in one request must share a namespace or be joined via EXISTS() in the filter. Key fields: ym:s:visits, ym:s:users, ym:s:pageviews, ym:s:bounceRate, ym:s:avgVisitDurationSeconds, ym:s:goal{ID}reaches, ym:s:goal{ID}conversionRate.

Full reference: references/dimensions-and-metrics.md

Filter DSL and segments

Operators: ==, !=, =@ (substring), !@ (no substring), =~ (regex), =* (glob with *), =n (null), =N (not null), >, <, >=, <=, IN(...), NOT IN(...). Logic: AND, OR, NOT. Cross-namespace: EXISTS(ym:pv:URL=='https://...'). Limits: up to 10 unique dimensions/metrics in a filter, 20 conditions, 10 000 chars, 100 values per IN(). filters is a one-shot segment; persistent segments are created via Management API.

Full reference: references/segments-and-filters.md

Logs API — raw-hit lifecycle

Workflow: (1) GET /management/v1/counter/{id}/logrequests/evaluate?date1=&date2=&fields=&source= — verify feasibility (free); (2) POST /management/v1/counter/{id}/logrequests?date1=&date2=&fields=&source=visits|hits — create the job, get request_id, status created; (3) poll GET /management/v1/counter/{id}/logrequest/{request_id} until status becomes processed (or processing_failed / awaiting_retry); (4) download chunks: GET /management/v1/counter/{id}/logrequest/{request_id}/part/{n}/download (count from parts[]); (5) POST /management/v1/counter/{id}/logrequest/{request_id}/clean — release storage. Sources: visits or hits. Limits: fields ≤ 3000 chars, range ≤ 1 year, total ≤ 10 GB per counter. Polling cadence: 30–60 s is reasonable.

Full reference: references/logs-api.md

Management API — CRUD

GET /management/v1/counters — accessible counters (fields id, name, site, permission, pro); GET /management/v1/counter/{id} — details; POST /management/v1/counters — create; PUT /management/v1/counter/{id} — update. Goals: GET/POST /management/v1/counter/{id}/goals, types url, number, step, composite, action. Filters: /counter/{id}/filters (bot/IP/domain exclusion). Operations: /counter/{id}/operations (URL cleanup — strip query params). Representatives: /counter/{id}/representatives.

Full reference: references/management-api.md

Errors, quota exhaustion, retry

HTTP 401 = invalid/expired token (reissue); 403 = no access to counter_id (check token owner); 429 = rate limit (honor Retry-After); 400 + quota_exceeded = 10 GB Logs cap; 400 + LimitedExceededException = daily request budget exhausted. Retry policy: exponential backoff 1→2→4→8 with jitter, cap 60 s; never retry 401/403/400.

Full reference: references/errors.md

Rate limits and concurrency strategy

Global: 30 req/s per IP (Reporting + Management), 10 req/s per IP for Logs API, 3 parallel per user_login, 5000 req/day per user_login (reset 00:00 GMT = 03:00 MSK), 200 req / 5 min on /stat/v1/data/. Logs API: 10 GB of prepared logs per counter. Recipe: asyncio.Semaphore(3), token-bucket at 30 req/s, response cache for 5–15 min on dashboards, daily counter in Redis.

Full reference: references/rate-limits.md

Production clients (Python + Node.js)

Ready-made templates: httpx.AsyncClient with OAuth, token-bucket for 30 req/s, asyncio.Semaphore(3), retry on 429/503 honoring Retry-After, daily counter in Redis, request_id persistence in Postgres, Logs API worker (submit → poll → download chunks → clean), TSV parsing for multi-touch attribution (first/last/linear), Node.js mirror on undici. PostgreSQL schema for daily aggregates + raw hits.

Full reference: references/integration.md

Quick reference