Search
API docs by Redocly

Analytics and Data (analytics)

Data on campaigns finances, promotion statistics, and seller analytics.

Analytics and Data

Data on campaigns finances, promotion statistics, and seller analytics.

Promotion Statistics

To access the methods, use a token for the Promotion category

Campaigns statistics{{ /adv/v2/fullstats }}

Описание метода

Returns campaign statistics.
Data will be returned for campaigns with statuses 7, 9, and 11

In the request, you can either pass the dates parameter or the interval parameter, but not both.
You can send a request with only the campaign ID. In this case, data for the last 24 hours will be returned, but not for the entire campaign period.
Maximum of 1 request per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
One of
[ 1 .. 100 ] items
Array ([ 1 .. 100 ] items)
id
integer

Campaign ID

dates
Array of strings <date> [ items <date > ]

Dates for which information needs to be provided.

Responses

Request samples

Content type
application/json
Example

Request with dates

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example

Response for a request with the field date

[
  • {
    }
]

Statistics of an automatic campaign by phrase clusters{{ /adv/v2/auto/stat-words }}

Описание метода

Returns clusters of key phrases (sets of similar ones) for which products were shown in the campaign, and the number of displays for them. Only those phrases for which products were shown at least once are included in the method's response.

Information is updated every 15 minutes.

Maximum of 4 requests per second per one seller's account
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
{
  • "excluded": [
    ],
  • "clusters": [
    ]
}

Campaign statistics by key phrases{{ /adv/v1/stat/words }}

Описание метода

The method allows to get search campaign statistics by key phrases.
The information updates approximately every half hour.

Maximum of 4 requests per second per one seller's account
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Responses

Response samples

Content type
application/json
{
  • "words": {
    },
  • "stat": [
    ]
}

Statistics on keywords for Automatic campaigns and Auctions{{ /adv/v0/stats/keywords }}

Описание метода

Returns statistics on keywords for each day the campaign was active.
Data can be retrieved for a maximum of 7 days in one request.
Information is updated every hour.

Maximum of 4 requests per second per one seller's account
Authorizations:
HeaderApiKey
query Parameters
advert_id
required
integer
Example: advert_id=123456789

Campaign ID

from
required
string <date>
Example: from=2024-08-10

Period start

to
required
string <date>
Example: to=2024-08-12

Period end

Responses

Response samples

Content type
application/json
{
  • "keywords": [
    ]
}

Receiving costs history{{ /adv/v1/upd }}

Описание метода

The method allows to get a costs history

Maximum of 1 request per second per one seller's account
Authorizations:
HeaderApiKey
query Parameters
from
required
string <date>
Example: from=2023-07-31

Beginning of the interval

to
required
string <date>
Example: to=2023-08-02

End of interval.
(Minimum interval is 1 day, maximum is 31)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Receiving the history of account top-ups{{ /adv/v1/payments }}

Описание метода

The method allows you to get a history of top-ups.

Maximum of 1 request per second per one seller's account
Authorizations:
HeaderApiKey
query Parameters
from
string <date>
Example: from=2023-07-31

Beginning of the interval

to
string <date>
Example: to=2023-08-02

End of interval.
(Minimum interval is 1 day, maximum is 31)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Media campaign statistics{{ /adv/v1/stats }}

Описание метода

The method allows to get statistics of media campaigns

Maximum of 60 requests per second per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
One of
[ 1 .. 100 ] items
Array ([ 1 .. 100 ] items)
id
integer

Campaign ID

dates
Array of strings <date> [ items <date > ]

Dates for which information needs to be provided.

Responses

Request samples

Content type
application/json
Example

Request with dates

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example

Response for interval queries

[
  • {
    }
]

Sales Funnel

To access the methods, use a token for the Analytics category

Time Zones

IANA format, the current list can be viewed here.

Retrieving product card (PC) statistics for a selected period, based on nmID/items/brands/tags{{ /api/v2/nm-report/detail }}

Описание метода

Retrieving statistics for product cards (PC) for a selected period, based on nmID/items/brands/tags.
The fields brandNames, objectIDs, tagIDs, nmIDs can be empty, in which case statistics for all product cards from the seller are included in the response.
When multiple fields are selected, the response includes data for cards that have all the selected fields. Pagination is supported. You can obtain a report for a maximum of one last year (365 days).

Also, in the data where information about the previous period is provided:

  • In previousPeriod, the data is for the same period as in selectedPeriod.
  • If the start date of previousPeriod is earlier than a year ago from the current date, it will be adjusted as follows: previousPeriod.start = current date - 365 days.
Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
brandNames
Array of strings

Brand name

objectIDs
Array of integers <int32> [ items <int32 > ]

Item Identifier

tagIDs
Array of integers <int32> [ items <int32 > ]

Numeric tag identifier

nmIDs
Array of integers <int32> [ items <int32 > ]

WB article

timezone
string

Timezone.
If not specified, the default is Europe/Moscow

required
object

Period

object

Sorting Parameters. If not specified, the default is "openCard" with descending order.

All sorting options field:
openCard — by card opening (transition to the product page)
addToCart — by additions to the cart
orders — by the number of orders
avgRubPrice — by average price in rubles
ordersSumRub — by the total order amount in rubles
stockMpQty — by the quantity of marketplace stock (pieces)
stockWbQty — by the quantity of warehouse stock (pieces)
cancelSumRub — by the sum of returns in rubles
cancelCount — by the number of returns
buyoutCount — by the number of buyouts
buyoutSumRub — by the total buyout amount in rubles

page
required
integer <int32>

Page

Responses

Request samples

Content type
application/json
{
  • "brandNames": [
    ],
  • "objectIDs": [
    ],
  • "tagIDs": [
    ],
  • "nmIDs": [
    ],
  • "timezone": "Europe/Moscow",
  • "period": {
    },
  • "orderBy": {
    },
  • "page": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Retrieving product card statistics for a period, grouped by items, brands, and tags{{ /api/v2/nm-report/grouped }}

Описание метода

Retrieving statistics for product cards for a period, grouped by items, brands, and tags.
The fields brandNames, objectIDs, tagIDs can be left empty, in which case grouping is done for all product cards from the seller. You can obtain a report for a maximum of one last year (365 days).

Also, in the data where information about the previous period is provided:

  • In previousPeriod, the data is for the same period as in selectedPeriod.
  • If the start date of previousPeriod is earlier than a year ago from the current date, it will be adjusted as follows: previousPeriod.start = current date - 365 days.
Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
objectIDs
Array of integers <int32> [ items <int32 > ]

Item Identifier

brandNames
Array of strings

Brand name

tagIDs
Array of integers <int32> [ items <int32 > ]

Numeric tag identifier

timezone
string

Timezone.
If not specified, the default is Europe/Moscow

required
object

Period

object

Sorting Parameters. If not specified, the default is "openCard" with descending order.

All sorting options field:
openCard — by card opening (transition to the product page)
addToCart — by additions to the cart
orders — by the number of orders
avgRubPrice — by average price in rubles
ordersSumRub — by the total order amount in rubles
stockMpQty — by the quantity of marketplace stock (pieces)
stockWbQty — by the quantity of warehouse stock (pieces)
cancelSumRub — by the sum of returns in rubles
cancelCount — by the number of returns
buyoutCount — by the number of buyouts
buyoutSumRub — by the total buyout amount in rubles

page
required
integer <int32>

Page

Responses

Request samples

Content type
application/json
{
  • "objectIDs": [
    ],
  • "brandNames": [
    ],
  • "tagIDs": [
    ],
  • "timezone": "Europe/Moscow",
  • "period": {
    },
  • "orderBy": {
    },
  • "page": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Retrieving product card statistics by days for selected nmID(s){{ /api/v2/nm-report/detail/history }}

Описание метода

Retrieving product card statistics by days for selected nmID(s). You can obtain a report for a maximum of one last week. To obtain reports for a period of up to one year, subscribe to Jam extended analytics.

Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
nmIDs
required
Array of integers <int32> [ items <int32 > ]

WB article (maximum 20)

required
object

Period

timezone
string

Timezone.
If not specified, the default is Europe/Moscow

aggregationLevel
string

Aggregation Type. If not specified, the default is aggregation by days.
Available aggregation levels: day, week, month

Responses

Request samples

Content type
application/json
{
  • "nmIDs": [
    ],
  • "period": {
    },
  • "timezone": "Europe/Moscow",
  • "aggregationLevel": "day"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Retrieving product card statistics by days for a period, grouped by items, brands, and tags{{ /api/v2/nm-report/grouped/history }}

Описание метода

Retrieving product card statistics by days for a period, grouped by items, brands, and tags.
The fields brandNames, objectIDs, tagIDs can be left empty, in which case grouping is done for all seller's product cards.
In the request, the product, brand, and tag count should not exceed 16. You can obtain a report for a maximum of one last week. To obtain reports for a period of up to one year, subscribe to Jam extended analytics.

Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
objectIDs
Array of integers <int32> [ items <int32 > ]

Item Identifier

brandNames
Array of strings

Brand name

tagIDs
Array of integers <int32> [ items <int32 > ]

Numeric tag identifier

required
object

Period

timezone
string

Timezone.
If not specified, the default is Europe/Moscow

aggregationLevel
string

Aggregation Type. If not specified, the default is aggregation

Responses

Request samples

Content type
application/json
{
  • "objectIDs": [
    ],
  • "brandNames": [
    ],
  • "tagIDs": [
    ],
  • "period": {
    },
  • "timezone": "Europe/Moscow",
  • "aggregationLevel": "day"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Search Queries

To access the methods, use a token for the Analytics category

These methods can be used to obtain a report on search queries.

You can use these methods only with Jam subscription

Main Page{{ /api/v2/search-report/report }}

Описание метода

Forms a dataset for the main report page with:

  • General information
  • Product positions
  • Data on visibility and transitions to the product card
  • Data for the table by groups

To obtain additional data in the table, use a separate request for:

  • Pagination by groups
  • Retrieval of products within a group

Additional parameters for selecting the list of products in the table:

  • positionCluster — average position in search
Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Current period

object (pastPeriod)

Previous period for comparison. Number of days — less than or equal to currentPeriod

nmIds
Array of integers <int32> [ items <int32 > ]

List of WB article numbers for filtering

subjectIds
Array of integers <int32> [ items <int32 > ]

List of subject IDs for filtering

brandNames
Array of strings

List of brands names for filtering

tagIds
Array of integers <int64> [ items <int64 > ]

List of tag IDs for filtering

positionCluster
required
string (PositionCluster)
Enum: "all" "firstHundred" "secondHundred" "below"

Which average search position of products to display in the report:

  • all — all
  • firstHundred — from 1 to 100
  • secondHundred — from 101 to 200
  • below — from 201 and below
required
object (OrderBy)

Soring parameters

limit
required
integer <uint32> <= 1000

Number of product groups in the response

offset
required
integer <uint32>

From which element to start outputting data

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "nmIds": [
    ],
  • "subjectIds": [
    ],
  • "brandNames": [
    ],
  • "tagIds": [
    ],
  • "positionCluster": "all",
  • "orderBy": {
    },
  • "limit": 130,
  • "offset": 50
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Pagination by Groups{{ /api/v2/search-report/table/groups }}

Описание метода

Pagination by groups in the report. It is possible only if there is a filter by brand, subject, or tag.

Additional parameters for selecting the list of products in the table:

  • positionCluster — average position in search
Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Current period

object (pastPeriod)

Previous period for comparison. Number of days — less than or equal to currentPeriod

nmIds
Array of integers <int32> [ items <int32 > ]

List of WB article numbers for filtering

subjectIds
Array of integers <int32> [ items <int32 > ]

List of subject IDs for filtering

brandNames
Array of strings

List of brands names for filtering

tagIds
Array of integers <int64> [ items <int64 > ]

List of tag IDs for filtering

required
object (OrderBy)

Soring parameters

positionCluster
required
string (PositionCluster)
Enum: "all" "firstHundred" "secondHundred" "below"

Which average search position of products to display in the report:

  • all — all
  • firstHundred — from 1 to 100
  • secondHundred — from 101 to 200
  • below — from 201 and below
limit
required
integer <uint32> <= 1000

Number of product groups in the response

offset
required
integer <uint32>

From which element to start outputting data

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "nmIds": [
    ],
  • "subjectIds": [
    ],
  • "brandNames": [
    ],
  • "tagIds": [
    ],
  • "orderBy": {
    },
  • "positionCluster": "all",
  • "limit": 130,
  • "offset": 50
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Pagination by Products Within a Group{{ /api/v2/search-report/table/details }}

Описание метода

Pagination by products within a group. It is possible regardless of the presence of filters.

Filters for pagination by products within a group or without filters:

  • tuple subjectId, brandName, tagId — filter for the group
  • nmIds — filter by nomenclature

Additional parameters for selecting the list of products in the table:

  • positionCluster — average position in search
Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Current period

object (pastPeriod)

Previous period for comparison. Number of days — less than or equal to currentPeriod

subjectId
integer <int32>

Subject ID

brandName
string

Product name

tagId
integer <int64>

Tag ID

nmIds
Array of integers <uint64> <= 50 items [ items <uint64 > ]

WB article numbers list

required
object (OrderBy)

Soring parameters

positionCluster
required
string
Enum: "all" "firstHundred" "secondHundred" "below"

Which average search position of products to display in the report:

  • all — all
  • firstHundred — from 1 to 100
  • secondHundred — from 101 to 200
  • below — from 201 and below
limit
required
integer <uint32> <= 1000

Number pf products in the response

offset
required
integer <uint32>

From which element to start outputting data

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "subjectId": 123,
  • "brandName": "Apple",
  • "tagId": 45,
  • "nmIds": [
    ],
  • "orderBy": {
    },
  • "positionCluster": "all",
  • "limit": 150,
  • "offset": 100
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Search Queries by Product{{ /api/v2/search-report/product/search-texts }}

Описание метода

Forms the top search queries by product.

Search query selection parameters:

  • limit — number of queries, maximum 30
  • topOrderBy — method for selecting the top queries
Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Current period

object (pastPeriod)

Previous period for comparison. Number of days — less than or equal to currentPeriod

nmIds
required
Array of integers <uint64> <= 50 items [ items <uint64 > ]

WB article numbers list

topOrderBy
required
string
Enum: "openCard" "addToCart" "openToCart" "orders" "cartToOrder"

Sorting by field:

  • openCard — transitioned to the product card from search
  • addToCart — added to the cart from search
  • openToCart — conversion to cart from search
  • orders — ordered products from search
  • cartToOrder — conversion to order from search
required
object (OrderBy)

Soring parameters

limit
required
integer <uint64> (TextLimit) [ 1 .. 30 ]

Number of search queries for the product

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "nmIds": [
    ],
  • "topOrderBy": "openToCart",
  • "orderBy": {
    },
  • "limit": 20
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Orders and Positions by Product Search Queries{{ /api/v2/search-report/product/orders }}

Описание метода

Forms data for a table on the number of orders and positions by queries. The data is specified within a period for a specific product

Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (PeriodOrdersRequest)

Current period. Maximum of 7 days

nmId
required
integer <uint64>

WB article

searchTexts
required
Array of strings [ 1 .. 30 ] items

Search query

Responses

Request samples

Content type
application/json
{
  • "period": {
    },
  • "nmId": 211131895,
  • "searchTexts": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Seller Analytics CSV

To access the methods, use a token for the Analytics category

You can use these methods only with Jam subscription.

To get a report:

  1. Generate it using the method Create the report.
  2. Wait until the report is ready. You can check the status with the method Get the reports list. The report is stored for 48 hours after it is ready, and it cannot be retrieved after.
    If you receive a status of FAILED, regenerate the report.
  3. Download the report.

You can obtain a report for a maximum of one year.

The maximum number of reports that can be generated per day is 20

Create the report{{ /api/v2/nm-report/downloads }}

Описание метода

You can create a report on sales funnel or search parameters with grouping:

  • by WB articles;
  • by categories, brands, and labels.

In each of reports on sales funnel, you can group data by days, weeks, or months.

Maximum of 3 requests per minute per one seller's account, and maximum of 20 reports can be generated per day (only successful generations are counted)
Authorizations:
HeaderApiKey
Request Body schema: application/json
One of
id
required
string <uuid>

Report ID in UUID format. Generated by the seller independently

reportType
required
string

Report type — DETAIL_HISTORY_REPORT

userReportName
string

Report name (if not specified, it will be generated automatically)

required
object

Report parameters

Responses

Request samples

Content type
application/json
Example

Sales funnel report. By WB articles

{
  • "id": "06eae887-9d9f-491f-b16a-bb1766fcb8d2",
  • "reportType": "DETAIL_HISTORY_REPORT",
  • "userReportName": "Card report",
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "data": "Created"
}

Get the reports list{{ /api/v2/nm-report/downloads }}

Описание метода
Maximum of of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
query Parameters
filter[downloadIds]
Array of strings <uuid> [ items <uuid > ]

Report ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Regenerate the report{{ /api/v2/nm-report/downloads/retry }}

Описание метода
Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
downloadId
string <uuid>

Report ID

Responses

Request samples

Content type
application/json
{
  • "downloadId": "06eea887-9d9f-491f-b16a-bb1766fcb8d2"
}

Response samples

Content type
application/json
{
  • "data": "Retry"
}

Get the report{{ /api/v2/nm-report/downloads/file/{downloadId} }}

Описание метода

You can get a report that was generated within the last 48 hours.
The report will be downloaded inside a ZIP archive in CSV format.

Maximum of 3 requests per minute per one seller's account
Authorizations:
HeaderApiKey
path Parameters
downloadId
required
string <uuid>

Report ID

Responses

Response samples

Content type
text/csv
Example
nmID, dt, openCardCount, addToCartCount, ordersCount, ordersSumRub, buyoutsCount, buyoutsSumRub, cancelCount, cancelSumRub, addToCartConversion, cartToOrderConversion, buyoutPercent
70027655,2024-11-21,1,0,0,0,0,0,0,0,0,0,0
...
...
150317666,2024-11-21,2,0,0,0,0,0,0,0,0,0,0