Quick start

Step 1. Get an OAuth token

Create an app and fill in the fields:
- Name: Any name of your choice.
- Service icon: Optional.
- Platforms: Select Web services.
- redirect URI: Specify https://oauth.yandex.com/verification_code.
- Data access: Specify a set of accesses for your app. Types of accesses:
  - metrika:read: Getting statistics, reading parameters of your own and trusted tags, getting a list of tags.
  - metrika:write: Creating tags, changing parameters of your own and trusted tags, uploading any data.
  - metrika:expenses: Uploading expenses to tags.
  - metrika:user_params: Uploading user parameters to tags.
  - metrika:offline_data: Uploading offline data (CRM data, offline conversions, calls) to tags.
Note

metrika:expenses, metrika:user_params, and metrika:offline_data accesses are optional if metrika:write is used.
Click Create app and copy its ClientID (next to the ID, click ).

Add the copied ClientID to the link as follows

https://oauth.yandex.com/authorize?response_type=token&client_id=<application_id>

Follow the link and copy your authorization token on the page that opens.

Troubleshooting

Error 403 (Access is denied) after obtaining a token

Possible reasons:

App-side

The app doesn't have access to Yandex Metrica. To read tag data (for example, to generate reports or view tag information), your app requires metrika:read access. To manage tags (for example, to upload offline data or edit tags and segments), your app requires metrika:write access.

Token-side

The token is invalid. The token expired or the authorization password for the associated account was changed. Issue another token.
The token was issued for another account. It may have been issued for a username that doesn't have access to the Yandex Metrica tag.

Warning

The token owner is not the app owner, but the account that was authorized when you made the GET request to obtain the token.
The token was created for another app. The GET request to obtain the token included an incorrect client_id value or a typo that resulted in the token being issued for an app that doesn't have metrika:read or metrika:write access to Yandex Metrica.

Yandex Metrica-side

The token owner doesn't have access to the tag that you're attempting to access via the API. Learn more about the types of tag access. The Management API requires owner, guest view, or guest write access.

API request-side

The token is read incorrectly or not at all due to incorrect authorization parameters in the API call code.

Error 401 (unauthorized) after obtaining a token

Possible reasons:

The authorization parameters in the request header are incorrect.
The header is missing authorization parameters.

Step 2. Choose an API to work with

Yandex Metrica offers three primary APIs:

Management API. This API allows you to create and edit tags, goals, filters, and other objects.
Data import API. With this API, you can import customer and order data from a CRM, as well as information about calls, offline conversions, and user parameters.
Reporting API. You can use this API to retrieve site traffic information and other data. Generate reports, including segmented and parameterized reports.
API Logs. Through this API, you can access non-aggregated data collected by Yandex Metrica. Choose this API if you process statistical data on your own or use it to tackle specific analytical challenges.

Step 3. Use the API to edit an object

To demonstrate, let's create a goal using the Management API:

First, select a tag for which you want to create the goal. To do this, call the GET https://api-metrica.yandex.net/management/v1/counters method and select the required tag from the list.

Request:

curl -i -X GET 'https://api-metrica.yandex.net/management/v1/counters' \
-H 'Authorization: OAuth 05dd3dd8...'

Response:

{
  "rows": 2,
  "counters": [
    {
      "id": 880000,
      "status": "Active",
      "owner_login": "example-developer",
      "code_status": "CS_ERR_UNKNOWN",
      "activity_status": "low",
      "name": "counter_option test example-developer",
      "type": "simple",
      "favorite": 0,
      "hide_address": 0,
      "pro": 0,
      "permission": "view",
      "webvisor": {
        "arch_enabled": 0,
        "arch_type": "none",
        "load_player_type": "proxy",
        "wv_version": 2,
        "allow_wv2": true,
        "notify_wv2": false,
        "wv_forms": 1
      },
      "code_options": {
        "async": 1,
        "informer": {
          "enabled": 0,
          "type": "ext",
          "size": 3,
          "indicator": "pageviews",
          "color_start": "FFFFFFFF",
          "color_end": "EFEFEFFF",
          "color_text": 0,
          "color_arrow": 1
        },
        "visor": 0,
        "track_hash": 0,
        "xml_site": 0,
        "clickmap": 1,
        "in_one_line": 0,
        "ecommerce": 0,
        "alternative_cdn": 0,
        "ecommerce_object": "dataLayer",
        "ytm": false
      },
      "create_time": "2022-03-25T15:59:52+03:00",
      "time_zone_name": "Europe/Moscow",
      "time_zone_offset": 180,
      "partner_id": 0,
      "site": "example-developer.ru",
      "site2": {
        "site": "example-developer.ru",
        "domain": "example-developer.ru"
      },
      "gdpr_agreement_accepted": 0,
      "delete_guest_allowed": 1
    },
    {
      "id": 87686941,
      "status": "Active",
      "owner_login": "example-manager",
      "code_status": "CS_ERR_UNKNOWN",
      "activity_status": "low",
      "name": "example-manager_1",
      "type": "simple",
      "favorite": 0,
      "hide_address": 0,
      "pro": 0,
      "permission": "edit",
      "webvisor": {
        "arch_enabled": 0,
        "arch_type": "none",
        "load_player_type": "proxy",
        "wv_version": 2,
        "allow_wv2": true,
        "notify_wv2": false,
        "wv_forms": 1
      },
      "code_options": {
        "async": 1,
        "informer": {
          "enabled": 0,
          "type": "ext",
          "size": 3,
          "indicator": "pageviews",
          "color_start": "FFFFFFFF",
          "color_end": "EFEFEFFF",
          "color_text": 0,
          "color_arrow": 1
        },
        "visor": 0,
        "track_hash": 0,
        "xml_site": 0,
        "clickmap": 1,
        "in_one_line": 0,
        "ecommerce": 0,
        "alternative_cdn": 0,
        "ecommerce_object": "dataLayer",
        "ytm": false
      },
      "create_time": "2022-03-02T16:06:27+03:00",
      "time_zone_name": "Europe/Moscow",
      "time_zone_offset": 180,
      "partner_id": 0,
      "site": "example-manager.ru",
      "site2": {
        "site": "example-manager.ru",
        "domain": "example-manager.ru"
      },
      "gdpr_agreement_accepted": 0,
      "delete_guest_allowed": 1
    }
  ]
}

To create a goal, use the POST https://api-metrica.yandex.net/management/v1/counter/{counterId}/goals method. Let's create a goal named MessengerGoal, which will track click-throughs to a specific messenger.

Request:

curl -i -X POST 'https://api-metrica.yandex.net/management/v1/counter/XXX/goals' \
-H 'Authorization: OAuth 05dd3dd8...' \
-H 'Content-Type: application/json' \

-d '{
       "goal": {
         "id": 0,
         "name": "MyMessengerGoal",
         "type": "messenger ",
         "conditions" : [{
           "type" :  "messenger", 
           "url" :  "whatsapp"
         }]
       }
 }'

Response:

HTTP/1.1 200 OK

{
   "goal": {
     "id": 222,
     "name": "MyMessengerGoal",
     "type": "messenger",
     "conditions" : [{
           "type" :  "messenger", 
           "url" :  "whatsapp"
         }]
     }
 }

Was the article helpful?

Authorization

Using logins to work with the API