API Reference: Dimensions & Metrics
Endpoints
| Endpoint |
Description |
/stat/v1/data |
Table report |
/stat/v1/data/bytime |
Time-series report (use with group) |
/stat/v1/data/drilldown |
Hierarchical drill-down |
/stat/v1/data/comparison |
Segment comparison |
Append .csv for CSV format: /stat/v1/data.csv
Visit Metrics (prefix: ym:s:)
| Metric |
Description |
ym:s:visits |
Total visits |
ym:s:users |
Unique visitors |
ym:s:pageviews |
Page views |
ym:s:bounceRate |
Bounce rate |
ym:s:pageDepth |
Pages per visit |
ym:s:avgVisitDurationSeconds |
Avg visit duration (sec) |
ym:s:crossDeviceUsers |
Cross-device unique visitors |
Goal Metrics (replace <goal_id>)
| Metric |
Description |
ym:s:goal<goal_id>visits |
Visits with goal achieved |
ym:s:goal<goal_id>reaches |
Total goal achievements |
ym:s:goal<goal_id>conversionRate |
Conversion rate (visits) |
ym:s:goal<goal_id>userConversionRate |
Conversion rate (users) |
ym:s:goal<goal_id>users |
Users who achieved goal |
Traffic Source Dimensions (replace <attribution>)
Attribution values: lastsign, last, first
| Dimension |
Description |
ym:s:<attr>TrafficSource |
Traffic source type |
ym:s:<attr>SourceEngine |
Detailed source (search engine name, etc.) |
ym:s:<attr>AdvEngine |
Ad system |
ym:s:<attr>ReferalSource |
Referral website |
ym:s:<attr>RecommendationSystem |
Recommendation system |
ym:s:<attr>Messenger |
Messenger |
UTM Dimensions (replace <attribution>)
| Dimension |
Description |
ym:s:<attr>UTMSource |
utm_source |
ym:s:<attr>UTMMedium |
utm_medium |
ym:s:<attr>UTMCampaign |
utm_campaign |
ym:s:<attr>UTMContent |
utm_content |
ym:s:<attr>UTMTerm |
utm_term |
Ecommerce Metrics (prefix: ym:s:)
| Metric |
Description |
ym:s:ecommercePurchases |
Total purchases |
Revenue metrics (replace <CUR> with RUB, USD, EUR, etc.):
| Metric |
Description |
ym:s:ecommerce<CUR>ConvertedRevenue |
Revenue in specified currency |
ym:s:ecommerce<CUR>ConvertedRevenuePerPurchase |
Avg check in specified currency |
ym:s:ecommerce<CUR>ConvertedRevenuePerVisit |
Revenue per visit in specified currency |
Pageview Metrics (prefix: ym:pv:)
IMPORTANT: ym:pv: metrics/dimensions CANNOT be mixed with ym:s: in one request.
| Metric / Dimension |
Description |
ym:pv:pageviews |
Page views |
ym:pv:users |
Unique users |
ym:pv:URLPathLevel1 |
URL path level 1 (usually just domain) |
ym:pv:URLPathLevel2..N |
Deeper URL path levels |
Ad Cost Metrics (prefix: ym:ad:)
IMPORTANT: ym:ad: metrics require direct_client_logins parameter. Cannot mix with ym:s: or ym:pv:.
| Metric |
Description |
ym:ad:visits |
Visits from Direct ads |
ym:ad:clicks |
Clicks in Direct |
ym:ad:RUBConvertedAdCost |
Ad cost in RUB |
ym:ad:USDConvertedAdCost |
Ad cost in USD |
ym:ad:EURConvertedAdCost |
Ad cost in EUR |
Ad Cost Dimensions (prefix: ym:ad:)
| Dimension |
Description |
ym:ad:date |
Date |
ym:ad:directOrder |
Direct campaign |
ym:ad:directBanner |
Ad creative |
ym:ad:directBannerGroup |
Ad group |
ym:ad:directPhraseOrCond |
Keyword / condition |
ym:ad:directPlatformType |
Platform type (search / network) |
ym:ad:directPlatform |
Specific platform |
Device & Technology Dimensions
| Dimension |
Description |
ym:s:deviceCategory |
desktop / mobile / tablet |
ym:s:operatingSystem |
OS |
ym:s:browser |
Browser |
ym:s:screenResolution |
Screen resolution |
Geography Dimensions
| Dimension |
Description |
ym:s:regionCountry |
Country |
ym:s:regionCity |
City |
ym:s:regionArea |
Region/area |
Common Parameters
| Parameter |
Description |
Default |
ids |
Counter ID(s), comma-separated |
required |
date1 |
Start date (YYYY-MM-DD) |
required |
date2 |
End date (YYYY-MM-DD) |
today |
metrics |
Metrics, comma-separated |
required |
dimensions |
Dimensions, comma-separated |
- |
filters |
Filter expression |
- |
accuracy |
0-1, where 1 = no sampling |
0.5 |
group |
day / week / month (bytime only) |
- |
limit |
Max rows |
100 |
offset |
Row offset for pagination |
1 |
sort |
Sort field (prefix - for desc) |
- |
Filter Syntax
ym:s:isRobot=='No'
ym:s:deviceCategory=='desktop'
ym:s:lastsignTrafficSource=='organic'
ym:s:regionCountry=='Россия' AND ym:s:deviceCategory=='mobile'
Operators: ==, !=, =@ (contains), !@ (not contains), =~ (regex), !~ (not regex)
Combine with AND, OR.
Known API Limitations
- Drilldown does not support CSV: requesting
/stat/v1/data/drilldown.csv (the .csv variant of the drilldown endpoint) returns HTTP 406 "Unsupported format" (verified by test). Use /stat/v1/data/drilldown (JSON) via metrika_get instead.
- Metric limit: at most 20 metrics per request.
conversions.sh requests six goals per batch (18 metrics), with up to two helper metrics, then combines the CSV batches.
- Bytime source limit:
/stat/v1/data/bytime selects 7 dimension values by default; top_keys allows up to 30. conversions.sh uses 30 by default and the same source sorting for every batch. Other report scripts still use the API default unless they explicitly set top_keys.
- searchPhrase + startURL = empty: combining
lastsignSearchPhrase and startURL dimensions returns 0 rows. Query them separately and correlate.
- URL Path Levels:
startURLPathLevel1 returns only the domain. Deeper levels require drilldown (which doesn't support CSV). Use startURL with =@ filter for section analysis instead.
- Pageview vs Visit scopes: cannot mix
ym:pv: and ym:s: prefixes in one query.
- Ad cost scope:
ym:ad:* is a separate scope requiring direct_client_logins. Cannot mix with ym:s: or ym:pv: in one query. Get logins via /management/v1/clients?counters=<id>.
- Search queries: Yandex hides ~70% of real search phrases. Only ~30% are available via API.
