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.
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_keycurl -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 status | error.code | Meaning |
|---|---|---|
400 | validation_error | Invalid query parameters. |
401 | invalid_api_key | The key is missing, malformed, unknown, revoked, or expired. |
403 | subscription_lapsed | The key is valid, but Premium isn't currently active. |
404 | not_found | No product with that id exists. |
429 | rate_limited | The per-minute request rate limit was exceeded — retry after Retry-After seconds. |
429 | quota_exceeded | The daily data quota is used up — it resets at 00:00 UTC. |
500 | internal_error | An internal server error — safe to retry later. |
503 | query_timeout | The 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). |
503 | service_unavailable | The 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.
| Limit | Value | What counts | When it resets | Error code |
|---|---|---|---|---|
| Request rate limit | 120 requests per minute | Every HTTP request | At the start of each minute | rate_limited |
| Daily data quota | 75,000 records per day | Records in responses | At 00:00 UTC | quota_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.
| Endpoint | What counts as a record |
|---|---|
GET /products | Each product in the response |
GET /products/{id} | The product (1 record) |
GET /products/{id}/price-history | Each price-history point |
GET /sellers | Each seller in the response |
GET /me/scrapes/{id}/products | Each 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.
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.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests left in the current minute |
X-RateLimit-Reset | Seconds until the next minute starts |
Retry-After | On 429 rate_limited and on 503: seconds to wait before retrying |
X-Quota-Limit | The key's daily quota |
X-Quota-Used | Records retrieved today, including this response |
X-Quota-Remaining | Records left until the end of the day |
X-Quota-Reset | Seconds 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_SYSCALLorConnection reset by peer; - JavaScript (Node.js,
fetch):TypeError: fetch failed, witherror.causeshowingECONNRESETorClient 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:
-
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.
-
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 theinterface:line showsutun…, requests go through the VPN; - Linux:
ip route get <IP>— ifdevis followed bytun…orwg…, requests go through the VPN; - Windows (PowerShell):
Find-NetRoute -RemoteIPAddress <IP>— if requests go through the VPN,InterfaceAliasshows 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.
- macOS:
-
Check proxy variables in your terminal (macOS/Linux):
env | grep -i proxy. -
On Windows, check for a certificate revocation error. The built-in
curl.exechecks whether the certificate has been revoked and refuses to connect if that check fails (CRYPT_E_NO_REVOCATION_CHECKorCRYPT_E_REVOCATION_OFFLINE). The--ssl-no-revokeflag turns this check off, so you can confirm it's the cause. Use it for diagnosis only. -
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
idyou resolve. It never changes — if you're polling the same product regularly (e.g. a brand reconciling its catalog daily), save theidfrom the first search and call directly byidfrom then on instead of repeatingGET /products— saves both a request and quota. unverified/flaggeddata is never hidden by default.trust_statusis 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 /productsis the one exception: it returnsmeta.has_moreinstead (see Bulk export).
Last updated on