https://api.nexscope.ai/amazon/opportunity/searchByMetricsRun this API
Send a JSON request to execute this API and receive the documented response payload.
Endpoint
| Method | POST |
| Path | https://api.nexscope.ai/amazon/opportunity/searchByMetrics |
| Auth | Bearer API key |
| Content-Type | application/json |
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
amazonDomain | string | optional | Amazon site code (closed enumeration), currently only supports `US`; if not specified, only the US site will be checked by default. |
limit | integer | optional | Returns the upper limit of the number of items; without the `page` parameter, the most recent N items are returned in reverse order of collection time. |
keyword | string | optional | Search keyword text fragments (LIKE fuzzy matching). |
nicheName | string | optional | Track normalized name fragment (LIKE, snake_case lowercase), suitable for track timing comparison. |
nicheRevenue360dMinUsdAtLeastGte | number | optional | The minimum value of the 360-day market revenue lower bound (USD). |
nicheRevenue360dMinUsdAtLeastLte | number | optional | The maximum value of the 360-day market revenue lower bound (USD). |
nicheRevenue360dMaxUsdAtLeastGte | number | optional | The minimum value of the 360-day market revenue upper bound (USD). |
nicheRevenue360dMaxUsdAtLeastLte | number | optional | The maximum value of the 360-day market revenue upper bound (USD). |
nichePeakSearchVolumeAtLeastGte | integer | optional | Lower bound for peak monthly search volume. |
nichePeakSearchVolumeAtLeastLte | integer | optional | The upper bound of peak monthly search volume. |
nicheSearchVolumeYoyChangePctAtLeastGte | number | optional | The lower limit of the year-on-year change rate of search volume (%, signed). |
nicheSearchVolumeYoyChangePctAtLeastLte | number | optional | The upper limit of the year-over-year change rate of search volume (%, signed). |
nichePeakMonthGte | integer | optional | Search peak month lower limit. |
nichePeakMonthLte | integer | optional | Search peak month cap. |
nicheBrandCountGte | integer | optional | Minimum number of active brands. |
nicheBrandCountLte | integer | optional | Maximum number of active brands. |
nicheBrandCountYoyChangePctAtLeastGte | number | optional | The lower limit of the year-on-year change rate of the number of brands (%, with sign). |
nicheBrandCountYoyChangePctAtLeastLte | number | optional | The upper limit of the year-on-year change rate of the number of brands (%, with sign). |
nicheTop5ProductClickSharePctAtLeastGte | number | optional | The lower limit for the click share of the top 5 products. |
nicheTop5ProductClickSharePctAtLeastLte | number | optional | The upper limit of the click share of the top 5 products. |
featureTop5BrandSharePctAtLeastGte | number | optional | The lower limit of the total share of the top 5 brands. |
featureTop5BrandSharePctAtLeastLte | number | optional | The upper limit of the total share of the top 5 brands. |
featureTopBrandsContains | string | optional | Top 3 brand name fragments (original text LIKE, case sensitive). |
priceMinUsdGte | number | optional | The lowest product price limit on the track (USD). |
priceMinUsdLte | number | optional | The track’s minimum product price limit (USD). |
priceMaxUsdGte | number | optional | The track’s maximum product price limit (USD). |
priceMaxUsdLte | number | optional | The track’s maximum product price limit (USD). |
priceSweetSpotMinUsdGte | number | optional | The lower bound of the Sweet Spot lower limit (USD). |
priceSweetSpotMinUsdLte | number | optional | The upper bound of the Sweet Spot lower limit (USD). |
priceSweetSpotMaxUsdGte | number | optional | Lower bound of Sweet Spot upper limit (USD). |
priceSweetSpotMaxUsdLte | number | optional | The upper bound of the Sweet Spot limit (USD). |
priceEntryClickSharePctAtLeastGte | number | optional | Minimum click share for entry-level users. |
priceEntryClickSharePctAtLeastLte | number | optional | The entry level click share limit. |
priceMidClickSharePctAtLeastGte | number | optional | Mid-range click share floor. |
priceMidClickSharePctAtLeastLte | number | optional | Mid-range click share cap. |
priceHighClickSharePctAtLeastGte | number | optional | The lower limit of click share for high-end products. |
priceHighClickSharePctAtLeastLte | number | optional | High-end click share limit. |
demoPrimaryAgeMinGte | integer | optional | The minimum value of the lower bound of the age of the main population. |
demoPrimaryAgeMinLte | integer | optional | The maximum value of the lower bound of the age of the host group. |
demoPrimaryAgeMaxGte | integer | optional | The minimum value of the upper bound of the age of the main population. |
demoPrimaryAgeMaxLte | integer | optional | The maximum value of the upper bound of the age of the host group. |
demoGenderDominant | string | optional | Gender dominant (closed enumeration): `female` / `male` / `mixed` / `unspecified`. |
demoPrimaryIncomeTier | string | optional | Income file (closed enumeration): `low` / `middle_low` / `middle` / `middle_upper` / `upper_middle` / `high`. |
demoLifeStageTagsContains | string | optional | Life stage tag fragment (snake_case, LIKE), such as `parent`, `student`, `retiree`, `athlete`. |
featureNewAvgReviewCountAtLeastGte | integer | optional | The lower limit for the average number of reviews for new products. |
featureNewAvgReviewCountAtLeastLte | integer | optional | The upper limit of the average number of reviews for new products. |
featureEstablishedAvgReviewCountAtLeastGte | integer | optional | The lower limit of the average number of comments for mature and old products. |
featureEstablishedAvgReviewCountAtLeastLte | integer | optional | The upper limit of the average number of comments for mature and old products. |
featureEmergingTrendTagsContains | string | optional | Emerging trend feature tag fragments (snake_case, LIKE), such as `cordless`, `portable`, `smart`. |
featureUncommonFeatureTagsContains | string | optional | Rare differentiation feature tag fragments (snake_case, LIKE), such as `hema_free`, `medical_grade_silicone`. |
searchTopCategory1Label | string | optional | Search traffic first type target tag fragment (snake_case, LIKE), such as `core_product_terms`, `set_kit_configurations`. |
reviewPositiveTop1Topic | string | optional | Like #1 theme snippets (snake_case, LIKE), such as `comfort`, `quality_overall_generic`. |
reviewPositiveTop1PctAtLeastGte | number | optional | The lower limit of the proportion of positive #1 topics (the proportion of positive comments). |
reviewPositiveTop1PctAtLeastLte | number | optional | The upper limit of the proportion of positive #1 topics. |
reviewNegativeTop1Topic | string | optional | Negative review #1 topic snippet (snake_case, LIKE), such as `size`, `quality`, `durability`. |
reviewNegativeTop1PctAtLeastGte | number | optional | The lower limit of negative review #1 topic proportion (proportion of negative reviews). |
reviewNegativeTop1PctAtLeastLte | number | optional | The upper limit for the proportion of negative review #1 topics. |
reviewNegativeTop2Topic | string | optional | Negative review #2 topic snippet (snake_case, LIKE). |
reviewStrategicInsightTagsContains | string | optional | Comment policy suggests tag snippets (snake_case, LIKE), such as `sizing_clarity`, `material_transparency`. |
Code example
{
"featureNewAvgReviewCountAtLeastLte": 500,
"limit": 25,
"nicheBrandCountLte": 20,
"nicheSearchVolumeYoyChangePctAtLeastGte": 100
}Response example
Platform response envelope. code 0 indicates success or acceptance; data contains the business result.
{
"code": 0,
"cost": "-1",
"data": {},
"msg": null,
"time": "2026-01-01 00:00:00",
"traceId": null,
"ts": "0"
}Response fields
| Name | Type | Required | Description |
|---|---|---|---|
code | integer | required | 0 means accepted or successful; nonzero is a platform error. |
cost | string | required | Elapsed milliseconds, never credits; -1 outside web requests. |
data | any | required | Data value used by this API operation. |
msg | string | null | required | Msg value used by this API operation. |
time | string | required | Server local time: yyyy-MM-dd HH:mm:ss. |
traceId | string | null | required | Trace id value used by this API operation. |
ts | string | required | Epoch milliseconds. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data | object | required | Data value used by this API operation. |
data.amazonDomain | any | optional | Amazon domain value used by this API operation. |
data.costTime | any | optional | Cost time value used by this API operation. |
data.costToken | any | optional | Cost token value used by this API operation. |
data.data | any | optional | Data value used by this API operation. |
data.dataSnapshotMonth | any | optional | Data snapshot month value used by this API operation. |
data.demoGenderDominant | any | optional | Demo gender dominant value used by this API operation. |
data.demoLifeStageTags | any | optional | Demo life stage tags value used by this API operation. |
data.demoPrimaryIncomeTier | any | optional | Demo primary income tier value used by this API operation. |
data.featureTop5BrandSharePctAtLeast | any | optional | Feature top5 brand share pct at least value used by this API operation. |
data.featureTopBrands | any | optional | Feature top brands value used by this API operation. |
data.keyword | any | optional | Keyword value used by this API operation. |
data.nicheName | any | optional | Niche name value used by this API operation. |
data.nichePeakMonth | any | optional | Niche peak month value used by this API operation. |
data.nichePeakSearchVolumeAtLeast | any | optional | Niche peak search volume at least value used by this API operation. |
data.nicheSearchVolumeYoyChangePctAtLeast | any | optional | Niche search volume yoy change pct at least value used by this API operation. |
data.nicheTop5ProductClickSharePctAtLeast | any | optional | Niche top5 product click share pct at least value used by this API operation. |
data.page | any | optional | Page value used by this API operation. |
data.pageItemCount | any | optional | Page item count value used by this API operation. |
data.pageSize | any | optional | Page size value used by this API operation. |
data.reviewStrategicInsightTags | any | optional | Review strategic insight tags value used by this API operation. |
data.searchTopCategory1Label | any | optional | Search top category1 label value used by this API operation. |
data.sourceTool | any | optional | Source tool value used by this API operation. |
data.sourceType | any | optional | Source type value used by this API operation. |
data.title | any | optional | Title value used by this API operation. |
data.totalPage | any | optional | Total page value used by this API operation. |
data.type | any | optional | Type value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.amazonDomain | string | optional | Site code, currently fixed to `US`. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.amazonDomain | null | optional | Amazon domain value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.costTime | integer | optional | Execution time reported by the upstream provider. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.costTime | null | optional | Cost time value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.costToken | integer | optional | Token cost reported by the upstream provider. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.costToken | null | optional | Cost token value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.data | array | optional | Keyword indicator record array, each corresponding to a (site, keyword) combination, about 37 fields, in reverse order of collection time. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.data | null | optional | Data value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.dataSnapshotMonth | string | optional | Data snapshot month returned by the upstream provider. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.dataSnapshotMonth | null | optional | Data snapshot month value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.demoGenderDominant | string | optional | Gender Dominant (`female` / `male` / `mixed` / `unspecified`). Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.demoGenderDominant | null | optional | Demo gender dominant value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.demoLifeStageTags | array | optional | List of life stage tags. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.demoLifeStageTags | null | optional | Demo life stage tags value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.demoPrimaryIncomeTier | string | optional | Income bracket of the core population. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.demoPrimaryIncomeTier | null | optional | Demo primary income tier value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.featureTop5BrandSharePctAtLeast | number | optional | Total share of top 5 brands (0-100). Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.featureTop5BrandSharePctAtLeast | null | optional | Feature top5 brand share pct at least value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.featureTopBrands | array | optional | Top3 brand name list (original text). Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.featureTopBrands | null | optional | Feature top brands value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.keyword | string | optional | Original search keyword. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.keyword | null | optional | Keyword value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.nicheName | string | optional | Track normalized name (snake_case). Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.nicheName | null | optional | Niche name value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.nichePeakMonth | integer | optional | Peak search months (1-12). Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.nichePeakMonth | null | optional | Niche peak month value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.nichePeakSearchVolumeAtLeast | integer | optional | Peak monthly search volume. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.nichePeakSearchVolumeAtLeast | null | optional | Niche peak search volume at least value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.nicheSearchVolumeYoyChangePctAtLeast | number | optional | Search volume year-over-year change rate (%, signed). Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.nicheSearchVolumeYoyChangePctAtLeast | null | optional | Niche search volume yoy change pct at least value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.nicheTop5ProductClickSharePctAtLeast | number | optional | Top5 product click share (0-100). Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.nicheTop5ProductClickSharePctAtLeast | null | optional | Niche top5 product click share pct at least value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.page | integer | optional | Current page returned by the upstream provider. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.page | null | optional | Page value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.pageItemCount | integer | optional | Item count on the current page returned by the upstream provider. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.pageItemCount | null | optional | Page item count value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.pageSize | integer | optional | Page size returned by the upstream provider. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.pageSize | null | optional | Page size value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.reviewStrategicInsightTags | array | optional | Comment policy suggestion tags. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.reviewStrategicInsightTags | null | optional | Review strategic insight tags value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.searchTopCategory1Label | string | optional | Normalized label of the first category of traffic. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.searchTopCategory1Label | null | optional | Search top category1 label value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.sourceTool | string | optional | Provider-specific source tool name. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.sourceTool | null | optional | Source tool value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.sourceType | string | optional | Provider-specific source platform type. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.sourceType | null | optional | Source type value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.title | string | optional | Provider-specific response title. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.title | null | optional | Title value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.totalPage | integer | optional | Total page count returned by the upstream provider. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.totalPage | null | optional | Total page value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.type | string | optional | Provider-specific render or payload type. Example: null |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.type | null | optional | Type value used by this API operation. |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data | null | required | Data value used by this API operation. |
Responses
| Code | Description |
|---|---|
| 200 | Default HTTP response for both success and many business errors. Only outer JSON code 0 indicates success or asynchronous acceptance; inspect data for the result. |
| 429 | Execution admission rate limit; honor Retry-After when present. |
| 503 | Execution admission is temporarily unavailable; honor Retry-After when present. |
| Opt-in | X-Nexscope-Http-Status: semantic maps controller-handled business errors to HTTP status on run and task routes. Pre-authentication failures, such as a missing API key (code 11209), may still return HTTP 200 before this mapping. Always check the outer JSON code; malformed requests and infrastructure failures may also return non-200 HTTP responses. |
Data source, freshness, and limitations
Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.