Ecommerce Ozon Product Report Search

Seerfar Ozon Product Report Search

This skill searches the Seerfar Ozon product database and filters products by rich performance metrics — monthly sales, revenue, growth, cart/order conversion, price, rating, reviews, brand, seller, fulfillment model, listing age, gross margin, and more. Each returned row is a full product-report record, making this the starting point for Ozon product selection (product selection), competitor product analysis, best-seller mining, and price/conversion-band screening.

Core Concepts

Unit of data is the product, not the keyword: this endpoint returns product-level rows (one per SKU), each enriched with full report metrics. You discover which products match your criteria — unlike the market-keyword endpoint, which returns search terms.

This is a product screener / product report: filter the Ozon product database by metric ranges ({min, max}), not only by keyword/brand/seller. Stack a high monthlySales floor with a low price ceiling to surface affordable high-volume products, or qualify conversion quality with a high convToCartPdp floor and a low returnCancellationRate ceiling; sort by sales DESC to mine best-sellers.

Unified vs raw duplicate fields: the response carries six alias pairs that hold the same value under two keys — sku/productId, sales/monthlySalesUnits, revenue/monthlySalesRevenue, reviewRating/rating, brandName/brand, productUrl/productPageUrl. Read either; do not expect them to differ.

Date semantics: searchDate selects the data month. Pass 2026-04-01 for March 2026 data; omit it for the last 30 days. Sales/revenue figures are relative to the selected period.

data and products are identical: both top-level arrays carry the same product rows. total is the total matching count (e.g. ~27.8M with no filter, 1 when filtering to a single SKU).

Ozon only: sourceType is fixed to ozon. fulfillment values are OZON, FBO, FBS, RFBS, FBP.

Parameters

All range filters are {min, max} objects; supply either or both bounds. Only page is required.

Calling the Tool

• API Endpoint: /seerfar/ozon/productReportSearch (full parameters/responses/error codes in references/api.md)
• Python Script: python scripts/ozon_product_report_search.py '<JSON params>' [--inline]
• Cost constraint: This tool consumes credits. Within the same session and same parameter combination, it defaults to a single call with a 24-hour local cache. Do not automatically retry with different keywords, pagination, or parameters on failure/empty results. Inform the user of additional credit consumption before continuing retrieval.

Output strategy (script default behavior):

• Always write the full response to <cwd>/nexscope/<YYYY-MM-DD>/<session>/data/ecommerce-ozon-product-report-search-<timestamp>.json (<cwd> is the working directory when the script executes, which in Claude Code is the current project directory; <session> is taken from the SESSION_ID environment variable, automatically grouped by user task; do not write to /tmp; error if the current directory is not writable)
• Response body <= 8 KB: write to disk then print full JSON to stdout
• Response body > 8 KB: write to disk then print only a summary to stdout (top-level fields, common counts like total/costToken, length of the largest list field + first 3 samples)
• Add --inline to force full output to stdout (still writes to disk)

Reading data: Check the summary first to determine if it is sufficient. When specific fields are needed, use jq or ConvertFrom-Json to extract from the saved JSON file as needed, avoiding loading the entire JSON into context.

Authentication & Credits

If you encounter authentication or credit issues:

Error conditions

• API Key not configured: The NEXSCOPE_API_KEY environment variable is not set.
• HTTP 401 or 402 status code
• Insufficient credits/balance: Response message indicates credit balance exhausted, quota exceeded, subscription expired, or recharge required.

Resolution steps

1. Set the NEXSCOPE_API_KEY environment variable with a valid API key.
2. If credits are insufficient, visit https://www.nexscope.ai/pricing?co-from=skillNS to top up your balance.
3. For onboarding and setup guidance, refer to https://www.nexscope.ai/help/skills-external-access?co-from=skillNS

Usage Examples

1. Top sellers right now (sort by sales)

{"page": {"page": 1, "pageSize": 10, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. Blue-ocean products — high sales, low price band

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}, "monthlySales": {"min": 5000}, "price": {"max": 500}}

3. Best-sellers in a category, FBO fulfillment

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}, "categoryIds": ["15621031_200000933_93182"], "fulfillment": ["FBO"], "labels": [2]}

4. New listings from the last 30 days, sorted by growth

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "salesRate", "direction": "DESC"}]}, "creationDate": 1}

5. Look up specific SKUs

{"page": {"page": 1, "pageSize": 10}, "skus": [2107989735]}

How to Build Queries

1. Lead with page.orders: the dataset is huge (tens of millions of products) — always sort by the metric you care about (sales DESC for best-sellers, salesRate DESC for rising products, price ASC for cheap volume, reviewRating DESC for well-reviewed).
2. Stack range filters to find opportunities: combine a monthlySales floor with a price ceiling, or a convToCartPdp floor with a low returnCancellationRate, to qualify demand-vs-risk.
3. Scope with categoryIds / brand / sellerName: narrow to a niche before sorting, so the top rows are relevant.
4. Use creationDate + labels for fresh demand: creationDate: 1 (new listings) paired with labels: [2] (best-seller badge) finds breakout products.
5. Pick the right searchDate: omit for current trends (last 30 days); pass an explicit date for month-over-month comparison.

Display Rules

1. Present data only: show product metrics in a clear table without subjective advice.
2. Lead with product columns: title, sku, price (₽), sales, revenue, rating, reviewCount, then brand / sellerName / fulfillment.
3. Currency: price/revenue/missedRevenue are in Russian rubles (₽); show the currency so scale is not misread.
4. Unified/raw aliases: prefer the unified fields (productId, monthlySalesUnits, monthlySalesRevenue, rating, brand, productPageUrl) or note they equal the raw ones — do not present both as if independent.
5. Large result sets: when total is large, show the top rows and remind the user they can persist the full response via the large-response pattern below, or page further with page.page.
6. Error handling: when code is not 200 (or errcode is not 200), explain the reason from msg / errmsg and suggest adjusting filters or retrying (rate-limit 1003).

Important Limitations

• page is required: a payload without page is rejected.
• skus cap: at most 10 SKUs per request.
• Category IDs are opaque: categoryIds requires Seerfar category IDs (from a category search), not human-readable names.
• Duplicate alias pairs: six fields are duplicated under raw + unified keys (see Core Concepts) — same value, two keys.
• total is the full match count: with no filter it can reach tens of millions; always sort and page rather than iterating blindly.
• Rate limiting: errcode 1003 ("request too frequent, please retry later") means throttle — wait and retry rather than lowering pageSize.
• Sort fields: valid orders[].field values are the response metric fields (e.g. sales, revenue, price, reviewRating, reviewCount, salesRate); the columns array marks which are sortable.

User Expression & Scenario Quick Reference

Applicable — Ozon product-level screening:

Not applicable — Needs beyond product-level reports:

• Keyword market data (search terms, search volume) → market-keyword-search.
• Keyword expansion around a seed term → keyword-mining.
• A specific shop's full catalog → shop-search.
• A category's products with category-level aggregates → category-search.
• Reverse keyword lookup for a product → keyword-back-search.
• Non-Ozon marketplaces → not covered here.

Boundary judgment: if the user wants to screen Ozon products by metrics and read product-level report rows, start here. If they want keyword-level market data, a single shop's catalog, or a category aggregate, route to the corresponding Seerfar Ozon data source.