# Amazon Business Insights Report API Reference
## API Specification
- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/amazon/opportunity/reportByKeyword`
- **HTTP Method**: POST, Content-Type: application/json
- **Authentication**: Header `Authorization: <api_key>`, read api_key from environment variable `NEXSCOPE_API_KEY` or `NEXSCOPE_API_KEY` (if not configured, follow **## Resolving Authentication and Credit Issues** in SKILL.md)
- **User-Agent**: `Nexscope-Skill/1.0`
## Request Parameters
POST Body (JSON):
| Parameter | Type | Required | Description |
|------|------|------|------|
| site | string | Yes | Amazon site code, currently only supports `US` |
| keyword | string | Yes | Search keyword for the insight report |
## Nexscope response envelope
These research endpoints return a platform object with numeric `code`, nullable `msg`, and business `data`. Only outer `code: 0` means success; `200`, string codes, missing codes, and HTTP 200 alone do not. A nonzero code is a platform error: show `msg` and do not interpret the payload as a successful result.
`msg` preserves the upstream message when available; Chinese messages are translated to English by Nexscope. A successful response without a message has `msg: null`. Do not infer success or retry behavior from the message text. On both success and failure, the direct fields `code`, `errcode`, `errorCode`, `msg`, `errmsg`, `message`, and `errorMsg` are removed from public `data`. Read the message only from outer `msg`; deeper business fields are preserved, including nested `code` and `status`.
Business field tables and abbreviated business examples below describe `data`, unless explicitly labeled as a complete platform response. For example, a business `products` field is at HTTP `data.products`, and a business `data` array is at HTTP `data.data`. The research endpoints already had this outer envelope; no additional wrapper is added.
```json
{"code":0,"msg":null,"data":{}}
```
Metadata includes string `ts` (epoch milliseconds), string `cost` (elapsed milliseconds, not credits), `time`, and nullable `traceId`. Handle network/HTTP failures before the platform code; gateway failures may not be platform JSON. Keep the existing billing-header guidance separate from elapsed time.
## Response Structure
| Field | Type | Description |
|------|------|------|
| stdout | string | Comprehensive business insight report content (Markdown format), covering six dimensions: market potential, product features, user reviews, customer profiles, search trends, and pricing analysis |
| costTime | integer | Total processing time (milliseconds) |
| costToken | integer | Token consumption |
| type | string | Response type |
The supplier's root `code` and `msg` are control fields. Nexscope maps them to the outer response envelope; they are not separate fields inside business `data`.
## Error Codes
HTTP 200 does not prove business success. Read only the numeric outer platform `code`: `0` succeeds and any other value fails. Show outer `msg`; never test removed provider codes or nested business `code` as the platform status. Authentication, permissions, balance, and validation failures may be platform errors even with HTTP 200; also handle non-2xx HTTP and non-JSON responses.
### Recovery guidance
| Condition | Action |
|---|---|
| Authentication failed | HTTP 401 or authorized error: follow **## Resolving Authentication and Credit Issues** in SKILL.md. |
| Insufficient credits | HTTP 402: follow **## Resolving Authentication and Credit Issues** in SKILL.md. |
## curl Example
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/amazon/opportunity/reportByKeyword \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-H "User-Agent: Nexscope-Skill/1.0" \
-d '{"site": "US", "keyword": "ice bricks"}'
```
---
## API Key request rate and retries
All API Keys of one Nexscope user share the public API execution request-rate allowance, measured in any rolling 1-second window. The allowed RPS depends on that user's entitlements; it is not a universal 1 RPS. One Skill operation may issue multiple public API requests, each of which uses the allowance.
HTTP 429 with Nexscope outer code `13012` means request-rate exhaustion: honor the response's `Retry-After`. Outer code `13013` means concurrent-request exhaustion, not rate exhaustion; honor `Retry-After` when supplied. Check the HTTP status and outer JSON code separately. Do not automatically replay writes or requests with uncertain outcomes; first reconcile the operation's state.