StoreRadar API

Authentication

Every request needs an API token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Authorization: token YOUR_API_TOKEN is accepted too, so older integrations keep working.

Two kinds of token

A token you create yourself on the API tokens page can call every endpoint on this page.

The token issued automatically for MCP and OAuth connections can only READ. It cannot create exports or download the database. Those credentials are held by third-party AI platforms, so their reach is deliberately smaller.

Call GET /health to see which one you are holding.

Base URL

Use the www host exactly as written. The bare domain redirects, and a redirect drops the body of a POST.

What each plan returns

Machine-readable

• OpenAPI 3.1 spec, for agent frameworks and client generators.
• llms.txt, a short index for language models.
• The same data is available over the Model Context Protocol. One token works on both.

GET /health

Confirms the token works and reports what it is allowed to do. It costs nothing against your rate limit, so call it first rather than discovering your tier from a refusal halfway through a job.

• unmasked: real domains and contacts are returned.
• verified: the verified-email filter is available.
• exports: this token may create exports and download the database.

GET /stores/search

A page of up to 20 stores matching your filters. Use /filter_options to learn the valid values, and /stores/count to size the segment first.

Pagination

Follow next_cursor. The cursor is opaque and carries the original filters and sort, so it wins over any filters you send alongside it. Send it on its own.

One query reaches at most about 520 rows. When you hit that edge you get has_more: true and NO next_cursor. That pair means the window ran out, not the segment. To take a whole segment, create an export instead of paging.

Masked and unmasked rows

Free accounts receive rows with the domain and contact values anonymized, and no named people. The annual plan returns the real values. Every row says which it is through masked.

Below 25 matches, a free account receives NO rows at all, only the count. A handful of anonymized rows plus their technology fingerprint would identify a single store.

Sorting

sort accepts: storeradar_score, seo_lite_score, product_count, collections_count, articles_count, pages_count, first_seen_at, last_detected_at, domain_created_at, domain_expires_at. sort_direction is asc or desc, defaulting to desc. Rows with no value in the sort column are left out, because a row that lacks the ranking value cannot be ranked by it.

GET /stores/count

How many stores match a filter set. It returns no store rows, so it is the cheapest way to size a segment before you search or export it.

Counts are strings

count is ALWAYS a string label, never a number. It can be an exact figure, a privacy range such as "fewer than 25", the cap "10000+", or "unknown" when the count could not be computed in time.

exact_count carries the integer, and it is present ONLY when the count is exact. Its absence is meaningful: it says the label is not a number. Search uses the same pair under the names total_count and exact_total_count.

Free accounts see the range for every result below 25, including a result of zero. That is deliberate: if zero answered differently from one, narrowing a filter until the answer changed would confirm that a specific store exists.

GET /filter_options

The valid values for each filter, read from the same caches the website's filter UI uses, so the two never disagree.

Call it with no parameters to list the categories, then again with ?category=. Technologies and apps return {name, id} pairs: pass the id into the technologies or shopify_apps filter, not the name. Add ?q= to narrow the long lists.

Available to every plan. No per-store data is involved.

GET /stores

One store by domain. Pass a bare hostname in ?domain=. The store arrives inside a store key, masked according to your plan.

Domains we have never seen

If the domain is not in the database, we queue it for analysis and answer 202. Poll the same URL. Within a minute or two you get either the store or a 404.

A 404 here is final. It means we looked and the domain does not serve a Shopify storefront we can publish. Polling it again will not change the answer.

New-domain analysis is capped at 10 domains per day, and there is a shared daily ceiling across all callers. Looking up domains that are already in the database is unaffected by either.

Named contacts

This is the only endpoint that returns people, the named contacts we have for a store with their role and email. It is present for annual subscribers only, and the key is absent entirely otherwise.

Exports

Two products. POST /exports generates a CSV of one filtered segment. GET /exports/full hands you the whole database as a nightly file.

Both need an active pass or annual plan, AND a token you created yourself. Tokens issued automatically for MCP or OAuth are read-only.

POST /exports

Send the same filters the search endpoint accepts. They have to narrow the scope: an empty filter set is refused, because the whole database is what /exports/full is for.

Filters your plan does not include are dropped, exactly as they are on search and count. The response tells you which: filters_applied is the scope that actually ran, and ignored_filters names anything removed. Read them before you describe the file to anyone.

One export runs per account at a time. A second request while one is running returns 409 with the export_id of the one already going, so poll that instead of retrying.

GET /exports/:id

Always 200 while the export exists. Branch on status, not on the HTTP code. Polling is metered on its own budget, so a poll every few seconds costs you nothing you need for store lookups:

download_url is a short-lived signed link in the body, not a redirect. Fetch it WITHOUT your Authorization header: the link carries its own signature and storage rejects a request that sends both.

truncated: true means the scope hit the 2,000,000-row ceiling, so the file is complete-looking but short. Narrow the filters and run it again.

Files are kept for 48 hours. After that the record stays and the file is gone, and a poll returns 410. Create the export again for a fresh copy.

GET /exports/full

A signed link to the current nightly export of the whole database. variant is verified for annual subscribers and verified add-on holders, and basic otherwise. The basic file has the email verification columns removed.

If the night's file is still being built you get 503 with error: "generating" and a Retry-After. That is a real state, not a failure. Try again in an hour.

Store fields

Every endpoint that returns a store returns these fields, in this shape. The table is generated from the serializer itself, so a field cannot be listed here without being produced, and the pipeline column names what fills it.

people

Returned by GET /stores only, and only for annual subscribers. The key is absent for every other caller.

What masking does to each field

• domain becomes dots plus the extension. The registrable part never survives.
• emails and phone_numbers keep their shape and lose their characters.
• social_media becomes a list of platform names with no handles.
• people is not returned at all.
• Everything else is identical for every plan.

Status codes

Error codes

Every response outside the 2xx range uses the same two keys: error, a stable machine-readable code, and message, text for a human. Branch on error. Some cases add one extra key, never removing these two.

Rate limits

Budgets are per endpoint and per account, shared with the MCP interface: spending a search there spends it here. Annual subscribers get 5 times the figures below.

Budget windows are aligned to the clock, so Retry-After is the real number of seconds until the window resets rather than an estimate. On a daily limit it can be large; treat it as advisory and retry after UTC midnight.

Changelog

September 2026: v1 rebuilt

GET /api/v1/stores ran on a credits system that no longer exists. The endpoint kept its URL and its store envelope; everything inside it changed. If you built against the old payload, read this list.

• Credits are gone. Lookups no longer charge anything and no longer create a lead record. The 402 Payment Required response no longer exists.
• The payload follows your plan. It used to return real emails and named contacts to any valid token. Free accounts now receive anonymized values, and people is returned to annual subscribers only.
• About twenty fields were removed, including id, name, lead_score, crawl_state, alive_status, meta_title, meta_description, locale, currency, pixels and lead. The field table is the complete list of what remains.
• Emails, phones, apps and technologies are arrays of strings. They used to be arrays of objects. The per-email verification columns are not returned by this endpoint at all; they ship in the verified CSV export.
• Timestamps are RFC3339. They used to render in a format that was not parseable as a date-time.
• The 202 body no longer carries job_id. It was an internal queue identifier with nothing to do.
• Expired tokens are rejected. A token past its expiry date used to keep working. Check yours on the API tokens page.
• Error bodies are machine-readable. error used to be a sentence; it is now a stable code from a closed list.

Added in the same release

• GET /health, GET /stores/search, GET /stores/count, GET /filter_options.
• POST /exports, GET /exports, GET /exports/:id, GET /exports/full.
• An OpenAPI 3.1 spec and an llms.txt index.