Market NinjaMarket Ninja

API Overview

How to get a key, authenticate, and start using the Market Ninja API — the resolve-then-fetch model, limits, error format.

The Market Ninja API gives programmatic read access to the same crowdsourced dataset you see in the extension's own UI: products, prices (current and historical), sellers, and categories from Wildberries, Ozon, Yandex Market, and Lamoda.

The API is read-only and can't trigger a scrape on demand — it only reads data that's already in the dataset. New products enter the dataset exclusively through the Market Ninja browser extension: if a product isn't there yet, scrape it with the extension first, then it becomes available through the API.
Server-to-server only. A secret key is a long-lived credential and must never touch code that runs in a browser — the same reason Stripe secret keys never do.

Getting a key

Issued from the extension's options page — API Keys section, available on the Premium tier. The full key value (mn_live_...) is shown exactly once, at creation time — save it immediately, it can't be recovered later (only revoked and reissued).

Authentication

Every request needs this header:

Authorization: Bearer mn_live_your_key
curl -H "Authorization: Bearer mn_live_..." \
  "https://data.marketninja.ru/v1/products?page_size=3"

Core usage model: "resolve, then fetch"

No external integrator knows our internal product id up front — nothing tells you that in advance. Instead, you always start with whatever you already have:

Find the product via GET /products, passing whatever you have: a product URL (url), the marketplace's own SKU (external_id + marketplace), or your own internal SKU (seller_code).

Read the id off the data[].id field in the response — our internal identifier.

If you need to, fetch that product directly by id (GET /products/{id}) or its price history (GET /products/{id}/price-history) — though note the current price is already in the response from step 1; the dedicated call is only for trend analysis.

Detailed scenarios with examples: Finding products, Price history, Sellers, Categories, Brands, Bulk export, Scrape sessions (retrieving what you just scraped via the extension), and Webhooks (get notified when a session finishes instead of polling). Full docs on parameters and responses for every endpoint: Reference.

Error format

Every error comes back in one shape:

{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key" } }
HTTP statuserror.codeMeaning
400validation_errorInvalid query parameters.
401invalid_api_keyThe key is missing, malformed, unknown, revoked, or expired.
403subscription_lapsedThe key is valid, but Premium isn't currently active.
404not_foundNo product with that id exists.
429rate_limitedThe per-minute request rate limit was exceeded — retry after Retry-After seconds.
429quota_exceededThe daily data quota is used up — it resets at 00:00 UTC.
500internal_errorAn internal server error — safe to retry later.
503query_timeoutThe query took too long. Wait Retry-After seconds and retry; if it keeps failing, narrow the request (for example, a longer name_contains term or an extra filter).
503service_unavailableThe service is temporarily busy — retry after Retry-After seconds.
403 and 401 are different problems for an integrator: "your key is wrong" (check the value) vs. "go resubscribe" (the key itself works, but access is paused). Don't handle them the same way in your code — the message shown to your user should differ.

Limits and quotas

API access is governed by two independent limits: request rate and daily data volume. Both apply to each API key separately. When either one is exceeded, the API responds with 429; the error.code field tells you which one it is.

LimitValueWhat countsWhen it resetsError code
Request rate limit120 requests per minuteEvery HTTP requestAt the start of each minuterate_limited
Daily data quota75,000 records per dayRecords in responsesAt 00:00 UTCquota_exceeded

Request rate limit

The request rate limit is the maximum number of requests a key can send in one minute: 120. When it's exceeded, the API responds with 429 and the code rate_limited. Every request counts, however many records it returns, including requests to /categories and /brands and requests rejected because the quota is used up.

The counter follows the clock minute: it resets at :00 seconds of every minute, not 60 seconds after your first request.

On a 429 rate_limited, wait the number of seconds given in Retry-After, then retry the same request.

Daily data quota

The daily data quota is the maximum number of records a key can retrieve through the API in one day: 75,000. Once it's used up, the API responds with 429 and the code quota_exceeded. It counts records in responses, not requests: a request with page_size=500 uses up to 500 records, a request with page_size=10 up to 10.

EndpointWhat counts as a record
GET /productsEach product in the response
GET /products/{id}The product (1 record)
GET /products/{id}/price-historyEach price-history point
GET /sellersEach seller in the response
GET /me/scrapes/{id}/productsEach product in the response (pending rows don't count)
GET /categories, GET /brands, GET /me/scrapes, GET /me/scrapes/{id}Don't use quota

The quota is checked before a request runs: if it isn't used up yet, the request is served in full, so the last request of the day can go slightly over it.

The quota limits how much you retrieve per day, not the dataset as a whole: after it resets at 00:00 UTC, you can continue where you left off. Each key's usage for the current day is shown on the API Keys page of your account.

On a 429 quota_exceeded, pause the export until the reset: until then the API will keep returning the same response. This response has no Retry-After header; X-Quota-Reset tells you how long to wait.

If 75,000 records a day isn't enough for your use case, message us on Telegram at @getmarketninja and we'll discuss a limit for your key.

Response headers

Every response except 401 and 403, successful ones included, carries headers with the current state of both limits. Use them to pace your requests before you ever hit a 429.

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute
X-RateLimit-RemainingRequests left in the current minute
X-RateLimit-ResetSeconds until the next minute starts
Retry-AfterOn 429 rate_limited and on 503: seconds to wait before retrying
X-Quota-LimitThe key's daily quota
X-Quota-UsedRecords retrieved today, including this response
X-Quota-RemainingRecords left until the end of the day
X-Quota-ResetSeconds until the quota resets

/categories and /brands don't use quota, so they return only the X-RateLimit-* headers.

Connection problems

If the connection drops before the server responds, you'll see one of these errors:

  • cURL: curl: (35) ... SSL_ERROR_SYSCALL or Connection reset by peer;
  • JavaScript (Node.js, fetch): TypeError: fetch failed, with error.cause showing ECONNRESET or Client network socket disconnected before secure TLS connection was established;
  • Python (requests): SSLError ... EOF occurred in violation of protocol.

This means the connection was dropped on the way to the server and the request never reached the API. Your key, subscription and limits aren't the cause: when something is wrong with them, the server always responds with an HTTP status and a JSON body (see Error format). If you got JSON back, the connection itself is fine.

The connection is most often cut by a VPN, a proxy, an antivirus that inspects HTTPS, or a corporate network filter. What to check:

  1. Fully quit the VPN app (exit it, don't just disconnect) and retry the request. Domain-based exclusions in VPN settings may not apply to scripts and curl, in which case their traffic still goes through the VPN.

  2. Check which network interface the traffic uses. Look up the server's IP with nslookup data.marketninja.ru (use the address at the end of the output, not the DNS server's address in the first lines), then run:

    • macOS: route -n get <IP> — if the interface: line shows utun…, requests go through the VPN;
    • Linux: ip route get <IP> — if dev is followed by tun… or wg…, requests go through the VPN;
    • Windows (PowerShell): Find-NetRoute -RemoteIPAddress <IP> — if requests go through the VPN, InterfaceAlias shows the VPN adapter's name.

    If you need the VPN on all the time, add this IP address to its exclusions. The address can change, so if the problem comes back, check it again.

  3. Check proxy variables in your terminal (macOS/Linux): env | grep -i proxy.

  4. On Windows, check for a certificate revocation error. The built-in curl.exe checks whether the certificate has been revoked and refuses to connect if that check fails (CRYPT_E_NO_REVOCATION_CHECK or CRYPT_E_REVOCATION_OFFLINE). The --ssl-no-revoke flag turns this check off, so you can confirm it's the cause. Use it for diagnosis only.

  5. Make sure your client supports TLS 1.2 or newer. The API doesn't accept older protocol versions.

If nothing helps, message us on Telegram at @getmarketninja with the full curl -v output (redact your key), the approximate time of the attempt, and the IP address you're connecting from (with a VPN on, the VPN server's public address).

Worth knowing

  • Cache the id you resolve. It never changes — if you're polling the same product regularly (e.g. a brand reconciling its catalog daily), save the id from the first search and call directly by id from then on instead of repeating GET /products — saves both a request and quota.
  • unverified/flagged data is never hidden by default. trust_status is always present in every product response — whether to trust a not-yet-corroborated record is your call, not something the API decides for you.
  • Pagination doesn't require knowing the page count up front — most list endpoints return an exact meta.total; read it from the response and keep going until you have what you need. GET /products is the one exception: it returns meta.has_more instead (see Bulk export).

Last updated on

On this page