### Install Yandex Metrica Skill

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/README.md

Use this command to install the skill using the Claude CLI. Alternatively, clone the repository manually.

```bash
claude skill install elsvv/yandex-metrica-skill
```

```bash
git clone https://github.com/elsvv/yandex-metrica-skill.git ~/.claude/skills/yandex-metrica
```

--------------------------------

### Direct Curl Example with Filter Syntax

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Make a direct API call using curl to get visits and bounce rate, filtered by device category. Ensure your OAuth token is set.

```bash
TOKEN="your_token"
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/stat/v1/data?ids=12345678&metrics=ym:s:visits,ym:s:bounceRate&dimensions=ym:s:browser&filters=ym:s:deviceCategory%3D%3D'2'&date1=2025-01-01&date2=2025-01-31&limit=20" | jq .
```

--------------------------------

### Setup - Configure OAuth Token

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Instructions on how to set up the Yandex Metrica Skill by configuring your OAuth token and optionally a default counter ID in the `.env` file.

```APIDOC
## Setup — Configure OAuth Token

Copy the example environment file and insert the OAuth token obtained from `https://oauth.yandex.ru`. The token requires at least `metrika:read` permission; `metrika:write` is needed for creating or modifying counters, goals, and filters.

```bash
# 1. Copy the template
cp config/.env.example config/.env

# 2. Edit config/.env and set your token:
#    YANDEX_METRICA_TOKEN=your_oauth_token_here
#    YANDEX_METRICA_COUNTER_ID=12345678   # optional default counter

# 3. Obtain a token via browser OAuth flow:
#    https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID
#    Copy the access_token value from the redirect URL fragment.

# 4. Verify the token works
bash scripts/check_connection.sh
# Expected output:
# Checking Metrica API connection...
# Metrica API: OK
# Available counters: 3
# First counter:
# { "id": 12345678, "name": "My Site", "site": "example.com" }
# Token is valid and API is accessible.
```
```

--------------------------------

### Get Technology Browser Breakdown

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Use the stats.sh script with the 'technology' preset to get browser usage statistics.

```bash
bash scripts/stats.sh --counter 12345678 --preset technology
```

--------------------------------

### Get Full Details of a Specific Goal

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Retrieve the complete configuration details for a single goal using its ID.

```bash
# Get full details of a specific goal
bash scripts/goals.sh --action get --counter 12345678 --goal-id 111
```

--------------------------------

### Get Report Data as CSV

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Downloads report data in CSV format by appending `.csv` to the endpoint. This example fetches visit data with a limit of 10 rows and saves it to `report.csv`.

```bash
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/stat/v1/data.csv?ids=12345678&metrics=ym:s:visits&limit=10" -o report.csv
```

--------------------------------

### Create Yandex Metrica Labels and Attach Counters

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Examples for creating labels and attaching counters using the Management API. Note the placeholder LABEL_ID which needs to be replaced with an actual ID.

```bash
TOKEN="your_token"
COUNTER=12345678
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":{"name":"Production"}}' \
  "https://api-metrika.yandex.net/management/v1/labels" | jq '{label_id: .label.id}'
```

```bash
TOKEN="your_token"
COUNTER=12345678
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/$COUNTER/label/LABEL_ID"
```

--------------------------------

### goals.sh - Get Goal Details

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Retrieves the full configuration details for a specific goal of a counter.

```APIDOC
## goals.sh - Get Goal Details

### Description
Fetches the complete configuration for a single, specified goal.

### Usage
```bash
bash scripts/goals.sh --action get --counter <COUNTER_ID> --goal-id <GOAL_ID>
```

### Example
```bash
# Get full details of a specific goal
bash scripts/goals.sh --action get --counter 12345678 --goal-id 111
```
```

--------------------------------

### Manage Yandex Metrica Counters

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

List, get details, or get summary information for counters. Includes direct curl examples for creating and updating counters.

```bash
# List all counters (tabular output)
bash scripts/counters.sh --action list
# Output:
# Total counters: 3
# 12345678   Production Site    example.com    Active
# 87654321   Staging            staging.io     Active

# Search counters by name or domain
bash scripts/counters.sh --action list --search "example.com"

# Get raw JSON details of a single counter
bash scripts/counters.sh --action get --counter 12345678

# Get counter with goals and filters summary
bash scripts/counters.sh --action info --counter 12345678
# Output:
# === Counter Info ===
# { "id": 12345678, "name": "Production Site", "site": "example.com", "status": "Active" }
# === Goals ===
# 111   Purchase      url
# 222   Form Submit   action
# === Filters ===
# 333   client_ip   interval   192.168.1.1–192.168.1.255

# Direct Management API calls (curl)
TOKEN="your_token"
# Create counter
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"counter":{"site":"example.com","name":"My Site"}}' \
  "https://api-metrika.yandex.net/management/v1/counters" | jq .

# Update counter name
curl -s -X PUT -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"counter":{"name":"Updated Name"}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678" | jq .
```

--------------------------------

### List Goals for a Counter

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Retrieve all goals configured for a specific counter. This helps in understanding the conversion tracking setup.

```bash
# List goals
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/goals" | jq .
```

--------------------------------

### Yandex Metrica Filter Syntax Examples

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/SKILL.md

Demonstrates various ways to filter data using Yandex Metrica dimensions, including equality, inequality, list membership, numerical comparison, substring matching, regex, and combining conditions.

```text
ym:s:trafficSource=='organic'           # equals
ym:s:trafficSource!='organic'           # not equals
ym:s:trafficSource=.('organic','direct') # in list
ym:s:pageViews>5                        # greater than
ym:s:startURL=@'product'               # contains
ym:s:startURL=~'.*product.*'           # regex
ym:s:trafficSource=='organic' AND ym:s:isRobot=='No'  # combine
```

--------------------------------

### Manage Yandex Metrica Filters

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Examples for managing counter-level traffic filters using the Management API. Use 'exclude' action for IP ranges and ensure 'active' status.

```bash
TOKEN="your_token"
COUNTER=12345678
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"attr":"client_ip","type":"interval","action":"exclude","start_ip":"192.168.1.1","end_ip":"192.168.1.255","status":"active"}}' \
  "https://api-metrika.yandex.net/management/v1/counter/$COUNTER/filters" | jq .
```

```bash
TOKEN="your_token"
COUNTER=12345678
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/$COUNTER/filters" | jq .
```

--------------------------------

### Yandex Metrica Reporting API: Filter Syntax Examples

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Illustrates various filter syntaxes for the Reporting API, including equals, not equals, in list, greater than, contains, regex, and combined conditions. Remember to URL-encode the filters parameter.

```bash
# equals:        ym:s:trafficSource=='organic'
# not equals:    ym:s:trafficSource!='direct'
# in list:       ym:s:trafficSource=.('organic','referral')
# greater than:  ym:s:pageViews>5
# contains:      ym:s:startURL=@'product'
# regex:         ym:s:startURL=~'.*checkout.*'
# combined:      ym:s:trafficSource=='organic' AND ym:s:deviceCategory=='1'
```

--------------------------------

### Get Authentication Token URL

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Use this URL to initiate the OAuth 2.0 authorization flow and obtain an access token. Ensure your application is registered and has the necessary permissions.

```bash
# Get token URL
https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID
```

--------------------------------

### counters.sh - Manage Counters

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Manage Yandex Metrica counters using the `counters.sh` script. This script supports listing all counters, retrieving details for a specific counter, and fetching a summary of counter information including goals and filters. It wraps the `GET /management/v1/counters` and `GET /management/v1/counter/{id}` API endpoints.

```APIDOC
## counters.sh — Manage Counters

Lists all counters, fetches a single counter's details, or retrieves full counter info including goals and filters. Wraps `GET /management/v1/counters` and `GET /management/v1/counter/{id}`.

```bash
# List all counters (tabular output)
bash scripts/counters.sh --action list
# Output:
# Total counters: 3
# 12345678   Production Site    example.com    Active
# 87654321   Staging            staging.io     Active

# Search counters by name or domain
bash scripts/counters.sh --action list --search "example.com"

# Get raw JSON details of a single counter
bash scripts/counters.sh --action get --counter 12345678

# Get counter with goals and filters summary
bash scripts/counters.sh --action info --counter 12345678
# Output:
# === Counter Info ===
# { "id": 12345678, "name": "Production Site", "site": "example.com", "status": "Active" }
# === Goals ===
# 111   Purchase      url
# 222   Form Submit   action
# === Filters ===
# 333   client_ip   interval   192.168.1.1–192.168.1.255

# Direct Management API calls (curl)
TOKEN="your_token"
# Create counter
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"counter":{"site":"example.com","name":"My Site"}}' \
  "https://api-metrika.yandex.net/management/v1/counters" | jq .

# Update counter name
curl -s -X PUT -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"counter":{"name":"Updated Name"}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678" | jq .
```
```

--------------------------------

### check_connection.sh - Verify API Access

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

This script verifies API access by calling the `GET /management/v1/counters` endpoint. It confirms token validity and API accessibility, displaying the total counter count and details of the first counter.

```APIDOC
## check_connection.sh — Verify API Access

Calls `GET /management/v1/counters` with `per_page=1` to confirm the token is valid and accessible. Prints the total counter count and the first counter's details.

```bash
bash scripts/check_connection.sh

# Output on success:
# Checking Metrica API connection...
# Metrica API: OK
# Available counters: 5
# First counter:
# {
#   "id": 12345678,
#   "name": "Production Site",
#   "site": "example.com"
# }
# Token is valid and API is accessible.

# Output on 401 / bad token:
# Metrica API: Error
# {"errors":[{"error_type":"invalid_oauth_token","message":"..."}]}
```
```

--------------------------------

### Perform URL Operations with Yandex Metrica API

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Use this example to strip UTM parameters from recorded URLs via the Management API. Ensure the 'attr' is set to 'url' and 'action' to 'cut_parameter'.

```bash
TOKEN="your_token"
COUNTER=12345678
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation":{"action":"cut_parameter","attr":"url","value":"utm_source","status":"active"}}' \
  "https://api-metrika.yandex.net/management/v1/counter/$COUNTER/operations" | jq .
```

--------------------------------

### Get Geography Visits by Country and City

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Use the stats.sh script with the 'geo' preset to retrieve geographical visit data.

```bash
bash scripts/stats.sh --counter 12345678 --preset geo
```

--------------------------------

### Get Table Report Data

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Retrieves aggregated data for a counter, supporting various metrics and dimensions. Specify date ranges, limits, and sorting. The `jq .` command is used to pretty-print the JSON output.

```bash
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/stat/v1/data?ids=12345678&metrics=ym:s:visits,ym:s:users,ym:s:bounceRate&dimensions=ym:s:trafficSource&date1=2025-01-01&date2=2025-01-31&limit=100" | jq .
```

--------------------------------

### Configure OAuth Token and Verify Connection

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Set up your Yandex Metrica OAuth token in the environment file and verify the connection to the API.

```bash
# 1. Copy the template
cp config/.env.example config/.env

# 2. Edit config/.env and set your token:
#    YANDEX_METRICA_TOKEN=your_oauth_token_here
#    YANDEX_METRICA_COUNTER_ID=12345678   # optional default counter

# 3. Obtain a token via browser OAuth flow:
#    https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID
#    Copy the access_token value from the redirect URL fragment.

# 4. Verify the token works
bash scripts/check_connection.sh
# Expected output:
# Checking Metrica API connection...
# Metrica API: OK
# Available counters: 3
# First counter:
# { "id": 12345678, "name": "My Site", "site": "example.com" }
# Token is valid and API is accessible.
```

```bash
bash scripts/check_connection.sh

# Output on success:
# Checking Metrica API connection...
# Metrica API: OK
# Available counters: 5
# First counter:
# {
#   "id": 12345678,
#   "name": "Production Site",
#   "site": "example.com"
# }
# Token is valid and API is accessible.

# Output on 401 / bad token:
# Metrica API: Error
# {"errors":[{"error_type":"invalid_oauth_token","message":"..."}]}
```

--------------------------------

### Obtain Yandex Metrica API Token

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/README.md

Run this script to set up your API token after registering an application on Yandex OAuth. Ensure you have the necessary 'metrika:read' and 'metrika:write' permissions.

```bash
bash ~/.claude/skills/yandex-metrica/scripts/get_token.sh --client-id YOUR_CLIENT_ID
```

--------------------------------

### List All Goals for a Counter

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Use the goals.sh script to list all conversion goals configured for a specific counter. The output is tab-separated.

```bash
# List all goals for a counter
bash scripts/goals.sh --action list --counter 12345678
```

--------------------------------

### Check Log Export Feasibility

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Use the logs.sh script to evaluate if raw data export is possible for a given date range. This is the first step in the export workflow.

```bash
# Step 1: Check if export is feasible for the date range
bash scripts/logs.sh --action evaluate --counter 12345678 \
  --date1 2025-01-01 --date2 2025-01-31
```

--------------------------------

### Get a Specific Yandex Metrica Counter

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Retrieve detailed information for a specific counter using its ID. This is useful for checking counter settings or status.

```bash
# Get counter
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678" | jq .
```

--------------------------------

### goals.sh - List Goals

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Lists all conversion goals configured for a specific counter.

```APIDOC
## goals.sh - List Goals

### Description
Retrieves a list of all conversion goals for a given counter.

### Usage
```bash
bash scripts/goals.sh --action list --counter <COUNTER_ID>
```

### Example
```bash
# List all goals for a counter
bash scripts/goals.sh --action list --counter 12345678
# Output (tab-separated):
# 111   Purchase      url      false
# 222   Form Submit   action   false
# 333   Phone Click   phone    false
```
```

--------------------------------

### Create Log Request

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Initiate a log request to retrieve data for a specified period. This is a POST request and requires the OAuth token, counter ID, date range, source, and desired fields.

```bash
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/logrequests?date1=2025-01-01&date2=2025-01-31&source=visits&fields=ym:s:visitID,ym:s:date,ym:s:dateTime,ym:s:startURL,ym:s:clientID,ym:s:deviceCategory,ym:s:regionCity,ym:s:goalsID"
```

--------------------------------

### Generate Time-Series Report for Daily Visits

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Generate a time-series report showing daily visits and users for a specified period. Use the 'bytime' type.

```bash
bash scripts/stats.sh --counter 12345678 --type bytime \
  --metrics "ym:s:visits,ym:s:users" \
  --date1 2025-01-01 --date2 2025-01-31
```

--------------------------------

### Create Label

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Creates a new label.

```APIDOC
## Create Label

### Description
Creates a new organizational label.

### Method
`POST`

### Endpoint
`https://api-metrika.yandex.net/management/v1/labels`

### Request Body
- `label` (object) - Required - The label details.
  - `name` (string) - Required - The name of the label.

### Request Example
```bash
TOKEN="your_token"
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":{"name":"Production"}}' \
  "https://api-metrika.yandex.net/management/v1/labels" | jq '{label_id: .label.id}'
```
```

--------------------------------

### Create an Action Goal

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Define a goal based on a specific user action, such as a button click or form submission. This requires specifying the action type and conditions.

```bash
# Create event goal
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":{"name":"Form Submit","type":"action","conditions":[{"type":"exact","url":"form_submit"}]}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/goals" | jq .
```

--------------------------------

### Create a JavaScript Event Goal

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Create a new JavaScript event goal using a POST request. Specify the goal name, type 'action', and conditions.

```bash
# Create a JavaScript event goal
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":{"name":"Form Submit","type":"action","conditions":[{"type":"exact","url":"form_submit"}]}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/goals" | jq .
```

--------------------------------

### Create a Yandex Metrica Counter

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Create a new counter for a website. This requires providing the site URL and a name for the counter. The response will contain the details of the newly created counter.

```bash
# Create counter
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"counter":{"site":"example.com","name":"My Site"}}' \
  "https://api-metrika.yandex.net/management/v1/counters" | jq .
```

--------------------------------

### Upload User Parameters (CSV)

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Uploads user parameters in CSV format to a counter. Use `--data-binary @user_params.csv` to specify the file. The `action` parameter can be 'update' or 'delete_keys', and `content_id_type` can be 'client_id' or 'user_id'.

```bash
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/x-yametrika+csv" \
  --data-binary @user_params.csv \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/user_params/uploadings?action=update&content_id_type=client_id"
```

--------------------------------

### Verify Yandex Metrica API Connection

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/README.md

Execute this script to confirm that your API token is valid and to list your Yandex Metrica counters.

```bash
bash ~/.claude/skills/yandex-metrica/scripts/check_connection.sh
```

--------------------------------

### Generate Yandex Metrica Reports with Presets

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/README.md

Use the stats script with predefined presets to quickly generate reports for traffic, sources, geography, content, or technology.

```bash
bash scripts/stats.sh --counter 12345678 --preset traffic
```

```bash
bash scripts/stats.sh --counter 12345678 --preset sources
```

```bash
bash scripts/stats.sh --counter 12345678 --preset geo
```

```bash
bash scripts/stats.sh --counter 12345678 --preset content
```

```bash
bash scripts/stats.sh --counter 12345678 --preset technology
```

--------------------------------

### Evaluate and Create Log Requests with Curl

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

These curl commands demonstrate how to evaluate and create log requests for Yandex Metrica data. Replace YOUR_TOKEN with your actual OAuth token.

```bash
TOKEN="your_token"
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/logrequests/evaluate?date1=2025-01-01&date2=2025-01-31&source=visits&fields=ym:s:visitID,ym:s:date,ym:s:startURL" | jq .
```

```bash
TOKEN="your_token"
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/logrequests?date1=2025-01-01&date2=2025-01-31&source=visits&fields=ym:s:visitID,ym:s:date,ym:s:startURL" | jq .
```

--------------------------------

### Create a URL Goal

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Add a new goal that tracks visits to a specific URL. This is useful for tracking page views, such as a thank-you page after a purchase.

```bash
# Create URL goal
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":{"name":"Purchase","type":"url","conditions":[{"type":"contain","url":"/thank-you"}]}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/goals" | jq .
```

--------------------------------

### List All Existing Log Requests

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

View a list of all previously created log requests for a given counter.

```bash
# List all existing log requests for a counter
bash scripts/logs.sh --action list --counter 12345678
```

--------------------------------

### Generate Custom Report for Organic Traffic with Goal Funnel

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Create a custom report for organic traffic, including visits, users, and goal funnel metrics. Specify date range, sorting, and limit.

```bash
bash scripts/stats.sh --counter 12345678 \
  --metrics "ym:s:visits,ym:s:users,ym:s:goal111reaches,ym:s:goal111conversionRate" \
  --dimensions "ym:s:lastTrafficSource" \
  --filters "ym:s:lastTrafficSource=='organic'" \
  --date1 2025-01-01 --date2 2025-01-31 \
  --sort "-ym:s:visits" \
  --limit 50
```

--------------------------------

### logs.sh - Evaluate Log Feasibility

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Checks if raw log data export is possible for a given date range.

```APIDOC
## logs.sh - Evaluate Log Feasibility

### Description
Determine if Yandex Metrica can provide raw log data for the specified period before initiating a request.

### Usage
```bash
bash scripts/logs.sh --action evaluate --counter <COUNTER_ID> \
  --date1 <START_DATE> --date2 <END_DATE>
```

### Example
```bash
# Step 1: Check if export is feasible for the date range
bash scripts/logs.sh --action evaluate --counter 12345678 \
  --date1 2025-01-01 --date2 2025-01-31
# Output:
# { "possible": true, "max_possible_day_quantity": 360 }
```
```

--------------------------------

### logs.sh - Create Log Request

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Initiates a request to export raw log data for a specified source and date range.

```APIDOC
## logs.sh - Create Log Request

### Description
Submit a request to Yandex Metrica to prepare raw log data for download.

### Usage
```bash
bash scripts/logs.sh --action create --counter <COUNTER_ID> \
  --source <SOURCE_TYPE> \
  --date1 <START_DATE> --date2 <END_DATE> \
  --fields "<FIELD1>,<FIELD2>"
```

### Parameters
- `source`: `visits` (session-level) or `hits` (pageview-level).
- `fields`: Comma-separated list of fields to include in the export.

### Example
```bash
# Step 2: Create the log request (returns request_id)
bash scripts/logs.sh --action create --counter 12345678 \
  --source visits \
  --date1 2025-01-01 --date2 2025-01-31 \
  --fields "ym:s:visitID,ym:s:date,ym:s:dateTime,ym:s:clientID,ym:s:startURL,ym:s:lastTrafficSource,ym:s:regionCity,ym:s:deviceCategory,ym:s:browser,ym:s:goalsID"
# Output:
# Created log request: 777 (status: created)
# Check status: bash scripts/logs.sh --action status --counter 12345678 --request-id 777
```
```

--------------------------------

### User Parameters Upload

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Upload and confirm user parameters for analysis.

```APIDOC
## POST /management/v1/counter/{counterId}/user_params/uploadings

### Description
Uploads user parameters in CSV format.

### Method
POST

### Endpoint
/management/v1/counter/{counterId}/user_params/uploadings

### Query Parameters
- **action** (string) - Required - The action to perform (e.g., `update`, `delete_keys`).
- **content_id_type** (string) - Required - The type of content ID (e.g., `client_id`, `user_id`).

### Request Body
--data-binary @user_params.csv

### Request Example
```bash
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/x-yametrika+csv" \
  --data-binary @user_params.csv \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/user_params/uploadings?action=update&content_id_type=client_id"
```
```

```APIDOC
## POST /management/v1/counter/{counterId}/user_params/uploading/{uploadId}/confirm

### Description
Confirms a previously initiated user parameters upload.

### Method
POST

### Endpoint
/management/v1/counter/{counterId}/user_params/uploading/{uploadId}/confirm

### Request Example
```bash
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/user_params/uploading/UPLOAD_ID/confirm"
```
```

--------------------------------

### logs.sh - Download Log Parts

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Downloads all processed parts of a raw log data export to a specified local directory.

```APIDOC
## logs.sh - Download Log Parts

### Description
Retrieve the exported raw log data files from Yandex Metrica servers.

### Usage
```bash
bash scripts/logs.sh --action download --counter <COUNTER_ID> \
  --request-id <REQUEST_ID> --output <OUTPUT_DIRECTORY>
```

### Example
```bash
# Step 4: Download all parts to a directory
bash scripts/logs.sh --action download --counter 12345678 \
  --request-id 777 --output ./exports
# Output:
# Downloading 3 part(s) to ./exports...
#   Part 0: 2,450,123 bytes → ./exports/log_12345678_777_part0.tsv
#   Part 1: 2,112,048 bytes → ./exports/log_12345678_777_part1.tsv
#   Part 2: 987,654 bytes → ./exports/log_12345678_777_part2.tsv
# Done.
```
```

--------------------------------

### Create a Yandex Metrica Label

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Create a new label to categorize your counters. Provide a name for the label in the JSON payload.

```bash
# Create label
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":{"name":"Production"}}' \
  "https://api-metrika.yandex.net/management/v1/labels" | jq .
```

--------------------------------

### Create a URL Goal via Curl

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Create a new URL-based conversion goal using a POST request to the goals API. Requires a valid OAuth token and JSON payload.

```bash
# Create a URL goal via curl
TOKEN="your_token"
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":{"name":"Thank You Page","type":"url","conditions":[{"type":"contain","url":"/thank-you"}]}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/goals" | jq .
```

--------------------------------

### Create Log Request for Raw Data Export

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Initiate a raw data log request using the logs.sh script. Specify the source ('visits' or 'hits'), date range, and desired fields. This returns a request ID.

```bash
# Step 2: Create the log request (returns request_id)
bash scripts/logs.sh --action create --counter 12345678 \
  --source visits \
  --date1 2025-01-01 --date2 2025-01-31 \
  --fields "ym:s:visitID,ym:s:date,ym:s:dateTime,ym:s:clientID,ym:s:startURL,ym:s:lastTrafficSource,ym:s:regionCity,ym:s:deviceCategory,ym:s:browser,ym:s:goalsID"
```

--------------------------------

### Confirm User Parameters Upload

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Confirms a previously initiated user parameters upload using the provided UPLOAD_ID.

```bash
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/user_params/uploading/UPLOAD_ID/confirm"
```

--------------------------------

### Create Log Request

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Create a log request to export data.

```APIDOC
## Create Log Request

### Description
Creates a log request to export data for a specified period and source.

### Method
`POST`

### Endpoint
`https://api-metrika.yandex.net/management/v1/counter/{counter}/logrequests`

### Parameters
#### Path Parameters
- `counter` (integer) - Required - The ID of the counter.

#### Query Parameters
- `date1` (string) - Required - Start date (YYYY-MM-DD).
- `date2` (string) - Required - End date (YYYY-MM-DD).
- `source` (string) - Required - Data source (e.g., `visits`).
- `fields` (string) - Required - Comma-separated list of fields.

### Request Example
```bash
TOKEN="your_token"
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/logrequests?date1=2025-01-01&date2=2025-01-31&source=visits&fields=ym:s:visitID,ym:s:date,ym:s:startURL" | jq .
```
```

--------------------------------

### Export Raw Yandex Metrica Logs

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/README.md

Initiate a raw data export using the Logs API. Specify the action, counter ID, data source, and date range. This action creates an export job.

```bash
bash scripts/logs.sh --action create --counter 12345678 \
  --source visits --date1 2025-01-01 --date2 2025-01-31
```

--------------------------------

### Create Yandex Metrica Segments

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Create a segment for mobile users using the Management API. The 'expression' parameter uses a specific syntax for defining segment criteria.

```bash
TOKEN="your_token"
COUNTER=12345678
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"segment":{"name":"Mobile Users","expression":"ym:s:deviceCategory=='"'2'"}}' \
  "https://api-metrika.yandex.net/management/v1/counter/$COUNTER/apisegment/segments" | jq .
```

--------------------------------

### logs.sh - List Log Requests

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Lists all existing raw log data export requests for a given counter.

```APIDOC
## logs.sh - List Log Requests

### Description
View a history of all log data export requests made for your counter.

### Usage
```bash
bash scripts/logs.sh --action list --counter <COUNTER_ID>
```

### Example
```bash
# List all existing log requests for a counter
bash scripts/logs.sh --action list --counter 12345678
```
```

--------------------------------

### Generate Custom Yandex Metrica Reports

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/README.md

Create custom reports by specifying metrics, dimensions, and date ranges. Requires Python 3 for URL encoding filters.

```bash
bash scripts/stats.sh --counter 12345678 \
  --metrics "ym:s:visits,ym:s:users,ym:s:bounceRate" \
  --dimensions "ym:s:lastTrafficSource" \
  --date1 2025-01-01 --date2 2025-01-31
```

--------------------------------

### Evaluate Log Request

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Evaluate a log request to preview data before creation.

```APIDOC
## Evaluate Log Request

### Description
Evaluates a log request to preview the data that would be exported. This is a GET request to check feasibility.

### Method
`GET`

### Endpoint
`https://api-metrika.yandex.net/management/v1/counter/{counter}/logrequests/evaluate`

### Parameters
#### Path Parameters
- `counter` (integer) - Required - The ID of the counter.

#### Query Parameters
- `date1` (string) - Required - Start date (YYYY-MM-DD).
- `date2` (string) - Required - End date (YYYY-MM-DD).
- `source` (string) - Required - Data source (e.g., `visits`).
- `fields` (string) - Required - Comma-separated list of fields.

### Request Example
```bash
TOKEN="your_token"
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/logrequests/evaluate?date1=2025-01-01&date2=2025-01-31&source=visits&fields=ym:s:visitID,ym:s:date,ym:s:startURL" | jq .
```
```

--------------------------------

### Statistics Presets

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Retrieve predefined statistics reports like geography, technology, or sources using presets.

```APIDOC
## Statistics Presets

### Description
Use the `--preset` flag with `stats.sh` to fetch common reports.

### Usage
```bash
bash scripts/stats.sh --counter <COUNTER_ID> --preset <PRESET_NAME>
```

### Presets
- `geo`: Geography breakdown (visits by country and city).
- `technology`: Technology breakdown (e.g., browsers).
- `sources`: Traffic sources.
```

--------------------------------

### goals.sh - Create Goal (curl)

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Creates a new conversion goal (URL or JavaScript event) for a counter using a curl request.

```APIDOC
## goals.sh - Create Goal (curl)

### Description
Programmatically add new goals to your Yandex Metrica counter.

### Endpoint
`POST https://api-metrika.yandex.net/management/v1/counter/<COUNTER_ID>/goals`

### Request Body
```json
{
  "goal": {
    "name": "<GOAL_NAME>",
    "type": "<GOAL_TYPE>",
    "conditions": [
      {
        "type": "<CONDITION_TYPE>",
        "url" or "value": "<CONDITION_VALUE>"
      }
    ]
  }
}
```

### Example: Create URL Goal
```bash
TOKEN="your_token"
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":{"name":"Thank You Page","type":"url","conditions":[{"type":"contain","url":"/thank-you"}]}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/goals" | jq .
```

### Example: Create JavaScript Event Goal
```bash
curl -s -X POST -H "Authorization: OAuth $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":{"name":"Form Submit","type":"action","conditions":[{"type":"exact","url":"form_submit"}]}}' \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/goals" | jq .
```
```

--------------------------------

### Fetch Aggregated Statistics

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Retrieve aggregated statistics using various presets like traffic overview or sources breakdown. Supports custom metrics, dimensions, filters, and date ranges.

```bash
# Traffic overview preset (last 30 days by default)
bash scripts/stats.sh --counter 12345678 --preset traffic
# Output:
# Period: 2025-01-01 — 2025-01-31
# Rows: 1 | Sampled: false
# === Totals ===
# ym:s:visits = 42500
# ym:s:pageviews = 130000
# ym:s:bounceRate = 38.2

# Traffic sources breakdown
bash scripts/stats.sh --counter 12345678 --preset sources

# Top pages by pageviews
bash scripts/stats.sh --counter 12345678 --preset content
```

--------------------------------

### Download CSV Report Directly from API

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Retrieve data directly in CSV format by appending '.csv' to the API endpoint. Save the output to a file using '-o'.

```bash
TOKEN="your_token"
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/stat/v1/data.csv?ids=12345678&metrics=ym:s:visits&limit=100" \
  -o report.csv
```

--------------------------------

### Create Raw Hits Export

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Use this script to create a raw hits export for a specified date range and fields. Ensure the correct counter ID and desired fields are provided.

```bash
scripts/logs.sh --action create --counter 12345678 \
  --source hits \
  --date1 2025-01-01 --date2 2025-01-07 \
  --fields "ym:pv:watchID,ym:pv:dateTime,ym:pv:clientID,ym:pv:URL,ym:pv:title,ym:pv:referer,ym:pv:UTMSource,ym:pv:UTMMedium"
```

--------------------------------

### Evaluate Log Request Data

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Use this endpoint to evaluate the data available for a given date range and source before creating a log request. Ensure you have the correct OAuth token and counter ID.

```bash
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/logrequests/evaluate?date1=2025-01-01&date2=2025-01-31&source=visits&fields=ym:s:visitID,ym:s:date,ym:s:startURL"
```

--------------------------------

### Create Log Request

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Creates a new log request for a specified counter and date range. This initiates the process of generating log data.

```APIDOC
## Create Log Request

### Description
Creates a new log request for a specified counter and date range. This initiates the process of generating log data.

### Method
POST

### Endpoint
https://api-metrika.yandex.net/management/v1/counter/{counterId}/logrequests

### Query Parameters
- **date1** (string) - Required - The start date for the log request (YYYY-MM-DD).
- **date2** (string) - Required - The end date for the log request (YYYY-MM-DD).
- **source** (string) - Required - The data source (e.g., 'visits').
- **fields** (string) - Required - Comma-separated list of fields to include in the log request.
```

--------------------------------

### Download Log Request Parts (TSV)

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Download a specific part of a processed log request. The `Accept-Encoding: gzip` header is recommended for compressed downloads. The output is saved to a file, e.g., `part0.tsv`.

```bash
curl -s -H "Authorization: OAuth $TOKEN" -H "Accept-Encoding: gzip" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/logrequest/777/part/0/download" -o part0.tsv
```

--------------------------------

### Download Log Data Parts

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Once a log request is processed, download all generated TSV data parts to a specified output directory. The script handles downloading each part.

```bash
# Step 4: Download all parts to a directory
bash scripts/logs.sh --action download --counter 12345678 \
  --request-id 777 --output ./exports
```

--------------------------------

### List Grants for a Counter

Source: https://github.com/elsvv/yandex-metrica-skill/blob/main/references/api-reference.md

Retrieve the list of users and their permissions for a specific counter. This allows you to manage access to your analytics data.

```bash
# List grants
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/12345678/grants" | jq .
```

--------------------------------

### List Filters

Source: https://context7.com/elsvv/yandex-metrica-skill/llms.txt

Retrieves all filters configured for a counter.

```APIDOC
## List Filters

### Description
Retrieves a list of all filters currently configured for a specific counter.

### Method
`GET`

### Endpoint
`https://api-metrika.yandex.net/management/v1/counter/{counter}/filters`

### Parameters
#### Path Parameters
- `counter` (integer) - Required - The ID of the counter.

### Request Example
```bash
TOKEN="your_token"
COUNTER=12345678
curl -s -H "Authorization: OAuth $TOKEN" \
  "https://api-metrika.yandex.net/management/v1/counter/$COUNTER/filters" | jq .
```
```