# Amazon Reviews

Extract Amazon product reviews—ratings, text, verification, helpful votes—from product URLs or ASINs on any marketplace, with an optional photos/videos-only mode

**Pricing:** $0.5 / 1k reviews

**Endpoint:** `POST /api/v1/agents/amazon/reviews/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `urls` | array | Yes | Amazon product URLs or bare ASINs — any marketplace. One per line. A URL keeps its own marketplace; bare ASINs use the Marketplace setting. |
| `marketplace` | string | No | Which Amazon site to pull reviews from. Applies to bare ASINs only — full URLs always use their own marketplace. |
| `maxResults` | integer | No | Reviews per product — applied to each product separately, so listing 3 products with a max of 10 returns up to 30 rows. Fetched in pages of 10; Amazon caps at 100 per product, and 0 also means the 100 max. |
| `onlyMediaReviews` | boolean | No | Set true to return only reviews that include photos or videos, with full-size image URLs and playable video URLs. |

## Example

```bash
curl -X POST https://api.mindcase.co/api/v1/agents/amazon/reviews/run \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"urls":["..."]}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/api/v1/agents/amazon/reviews/run",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {
    "urls": [
        "..."
    ]
}},
)
data = resp.json()
```

## Get the results

`run` is async and returns a `job_id`. Poll until `status` is `completed`, then read the rows:

```bash
# 1) check status
curl https://api.mindcase.co/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/api/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, endpoints): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `reviewTitle` | Review Title | text |
| `reviewText` | Review Text | text |
| `rating` | Rating | number |
| `posted` | Posted | text |
| `reviewer` | Reviewer | text |
| `reviewerUrl` | Reviewer URL | text |
| `verifiedPurchase` | Verified Purchase | boolean |
| `amazonVine` | Amazon Vine | boolean |
| `helpfulVotes` | Helpful Votes | number |
| `language` | Language | text |
| `variant` | Variant | array |
| `variantAsin` | Variant ASIN | text |
| `images` | Images | array |
| `videos` | Videos | array |
| `mediaType` | Media Type | text |
| `reviewUrl` | Review URL | text |
| `reviewId` | Review ID | text |
| `asin` | ASIN | text |
| `country` | Country | text |
| `productTitle` | Product Title | text |
| `productRating` | Product Rating | number |
| `productRatingsTotal` | Product Ratings (Total) | number |
| `productReviewsTotal` | Product Reviews (Total) | number |
| `fiveStar` | Five Star % | number |
| `fourStar` | Four Star % | number |
| `threeStar` | Three Star % | number |
| `twoStar` | Two Star % | number |
| `oneStar` | One Star % | number |
| `productCategory` | Product Category | text |