> Documentation index: https://docs.scrapier.io/llms.txt
> Auth: header `X-API-Key: <key>` · Base: https://api.scrapier.io/api/v2 · Synchronous; paginate with `cursor` ← `data.next_cursor`.

# Etsy Product Reviews

Structured Etsy data: send `urls`. Cursor-paginated, 1 credit per successful call.

`GET|POST https://api.scrapier.io/api/v2/etsy-product-reviews/` · 1 credit per successful call · Cursor-paginated

## Overview

Call `GET /api/v2/etsy-product-reviews/` with `urls`. The results are in `data.reviews`; send `data.next_cursor` back as `cursor` to get the next page. 4 optional parameters refine the call (see Parameters).

## Request

```bash
curl -G "https://api.scrapier.io/api/v2/etsy-product-reviews/" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "urls=RosysPatterns" \
  --max-time 210
```

```python
import requests

resp = requests.get(
    "https://api.scrapier.io/api/v2/etsy-product-reviews/",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"urls": "RosysPatterns"},
    timeout=210,
)
body = resp.json()
if not resp.ok:
    raise RuntimeError(body.get("error") or body.get("detail"))

print(body["data"]["reviews"])
```

POST with a JSON body works too (same parameters; the body is merged over the query string).

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `X-API-Key` (header) | string | yes | — | Your API key. |
| `urls` | string | yes | e.g. `RosysPatterns` | Etsy listing URL / listing id (product reviews) or shop URL / shop name (shop reviews). Required on the first call (list -> first only). 24 reviews per page. |
| `cursor` | string | no | — | Pagination cursor returned in the previous response's `next_cursor`. Pass it back unchanged to fetch the next page. When `next_cursor` is null, you have reached the last page. |
| `sort_option` | string | no | `Recency` | One of: `Recency`, `Relevancy`, `Highest`, `Lowest`. Locked in cursor. |
| `enrich_buyer_profiles` | boolean | no | `false` | Locked in cursor. |
| `include_subratings` | boolean | no | `false` | Best-effort (DataDome-gated). Locked in cursor. |
| `use_proxy` | boolean | no | `true` | Route the request through Scrapier's residential proxy pool. Default: `true`. Leave as is unless support tells you otherwise. |
| `raw_data` | boolean | no | `false` | When true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under `raw_responses`, in place of the formatted items. When false (default) you get the formatted output. Pagination (`cursor` / `next_cursor`) works the same in both modes. |

## Response

HTTP 200. Results are in `data.reviews`. Sample from the live catalog, arrays trimmed to 3 items.

```json
{
  "success": true,
  "data": {
    "urls": "RosysPatterns",
    "review_type": "shop",
    "shop_name": "RosysPatterns",
    "shop_id": 42510206,
    "listing_id": null,
    "total_reviews": 2074,
    "page": 1,
    "page_size": 24,
    "reviews": [
      {
        "input_url": "RosysPatterns",
        "review_type": "shop",
        "receipt_id": 5218626147,
        "buyer_user_id": 66570233,
        "buyer_real_name": "Flop",
        "buyer_login_name": "dorisgt",
        "buyer_image": "https://i.etsystatic.com/iusa/c4ae13/31745354/iusa_75x75.31745354_97zs.jpg?version=0",
        "listing_title": "Whole Shop 113 Rosys Patterns Sewing Patterns, Beginner Sewing Patterns, XXS-XXL, Bundle Set, Sewing Instructions, US Letter-A4-A0 Format",
        "review": "The seller is really lovely and talented. I haven't had a chance to sew any patterns yet, but I have no doubt they'll be beautiful. I'm so happy that the photos aren't ai generated. Love supporting creative and hardworking creators 💙",
        "appreciation_image": null,
        "product_rating": 5,
        "response": null,
        "reviews_count": 30,
        "date": "2026-09-26 06:36:27",
        "recommends": false,
        "subratings": {},
        "product_details": {
          "shop_average_rating": 4.56,
          "shop_total_rating_count": 2074,
          "product_url": "https://www.etsy.com/listing/1791096370/whole-shop-113-rosys-patterns-sewing",
          "seller_name": "RosysPatterns",
          "seller_url": "https://www.etsy.com/shop/RosysPatterns",
          "reviewer_image": "https://i.etsystatic.com/42510206/r/il/55843f/8248553529/il_fullxfull.8248553529_agtm.jpg",
          "image": [
            "https://i.etsystatic.com/42510206/r/il/55843f/8248553529/il_fullxfull.8248553529_agtm.jpg",
            "https://i.etsystatic.com/42510206/r/il/55843f/8248553529/il_75x75.8248553529_agtm.jpg",
            "https://i.etsystatic.com/42510206/r/il/55843f/8248553529/il_170x135.8248553529_agtm.jpg"
          ]
        },
        "listing_id": 1791096370,
        "shop_id": 42510206,
        "position": 1,
        "page": 1,
        "sort_option": "Recency",
        "scraped_at": "2026-09-26T11:02:37.564Z"
      }
    ],
    "next_cursor": "eyJpIjoiUm9zeXNQYXR0ZXJucyIsImxpZCI6MTkwNjA4NjY1OSwibGsiOnsiZW5yaWNoX2J1eWVyX3Byb2ZpbGVzIjp0cnVlLCJpbmNsdWRlX3N1YnJhdGluZ3MiOmZhbHNlLCJzb3J0X29wdGlvbiI6IlJlY2VuY3kifSwibHIiOm51bGwsIm0iOiJzaG9wIiwibiI6MjQsIm5wIjo0LCJwIjoyLCJzIjpbNTIxODYyNjE0Nyw1MjE4ODg0MDgxLDUxNjc1ODY4NDAsNTIyMzQ0MTkzNiw1MjIxMDQwNjQ1LDUyMDYxMjY0NzYsNTEyOTYwMzUwMCw1MTc5NjA4MzA0LDUyMTc1MDEzMzcsNTIxMjE0MjY2NCw1MjEwMTE5NjQ3LDUxMjEyNjYxMjgsNTExNjY4MTA5OSw1MTI2NDk0MjU1LDUxODUwOTcyNzksNTEyMDk3ODE5NSw1MTM2OTc2ODA4LDUyMDcwODI0ODEsNTEzMjQyNzczNiw1MjAxMjkyMjQ1LDUxNjQyODgzNTcsNTE2NTMzOTE4Miw1MTMwOTQ5Mjc0LDUwODI0NjM1OTFdLCJzYSI6NC41Niwic2QiOlsxOTA2MDg2NjU5LDE4NjIzMzAyNTcsNDQwNTg0MzIyMl0sInNpZCI6NDI1MTAyMDYsInNuIjoiUm9zeXNQYXR0ZXJucyIsInN0IjoyMDc0fQ"
  }
}
```

## Response fields

| Field | Type | Example | Description |
|---|---|---|---|
| `urls` | string | `RosysPatterns` |  |
| `review_type` | string | `shop` |  |
| `shop_name` | string | `RosysPatterns` |  |
| `shop_id` | integer | `42510206` |  |
| `listing_id` | null | `null` |  |
| `total_reviews` | integer | `2074` |  |
| `page` | integer | `1` |  |
| `page_size` | integer | `24` |  |
| `reviews` | array | `[1 item]` | The results. |
| `next_cursor` | string | `eyJpIjoiUm9zeXNQYXR0ZXJucyIsImxpZCI6MTkwNjA4N…` | Pass back as `cursor` for the next page. `null` on the last page. |
| `reviews[].input_url` | string | `RosysPatterns` |  |
| `reviews[].review_type` | string | `shop` |  |
| `reviews[].receipt_id` | integer | `5218626147` |  |
| `reviews[].buyer_user_id` | integer | `66570233` |  |
| `reviews[].buyer_real_name` | string | `Flop` |  |
| `reviews[].buyer_login_name` | string | `dorisgt` |  |
| `reviews[].buyer_image` | string | `https://i.etsystatic.com/iusa/c4ae13/31745354…` |  |
| `reviews[].listing_title` | string | `Whole Shop 113 Rosys Patterns Sewing Patterns…` |  |
| `reviews[].review` | string | `The seller is really lovely and talented. I h…` |  |
| `reviews[].appreciation_image` | null | `null` |  |
| `reviews[].product_rating` | integer | `5` |  |
| `reviews[].response` | null | `null` |  |
| `reviews[].reviews_count` | integer | `30` |  |
| `reviews[].date` | string | `2026-09-26 06:36:27` |  |
| `reviews[].recommends` | boolean | `false` |  |
| `reviews[].subratings` | object | `{…}` |  |
| `reviews[].product_details` | object | `{…}` |  |
| `reviews[].listing_id` | integer | `1791096370` |  |
| `reviews[].shop_id` | integer | `42510206` |  |
| `reviews[].position` | integer | `1` |  |
| `reviews[].page` | integer | `1` |  |
| `reviews[].sort_option` | string | `Recency` |  |
| `reviews[].scraped_at` | string | `2026-09-26T11:02:37.564Z` |  |

## Pagination

Pass `data.next_cursor` back as `cursor` until it is `null`. Required inputs are ignored once a cursor is sent. Each page is one billed call.

```python
import requests

URL = "https://api.scrapier.io/api/v2/etsy-product-reviews/"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
params = {"urls": "RosysPatterns"}
items = []

for _ in range(10):  # each page is one billed call
    resp = requests.get(URL, headers=HEADERS, params=params, timeout=210)
    resp.raise_for_status()
    data = resp.json()["data"]
    items.extend(data.get("reviews") or [])
    if not data.get("next_cursor"):  # None = last page
        break
    params = {"cursor": data["next_cursor"]}
```

## Errors

Failed calls are free. Branch on HTTP status; the message is in `error` (or `detail`). See https://docs.scrapier.io/errors.md

- **400** Bad input. The exact message varies by endpoint. `{"success":false,"error":"…"}`
- **402** Balance below the endpoint's price. `{"error":"Insufficient credits. Buy more to scrape more.","balance":1,"required":2}`
- **403** Invalid or unknown API key. `{"detail":"Authentication service unavailable or invalid API key."}`
- **429** Throttled — wait for Retry-After. `{"detail":"Request was throttled. Expected available in N seconds."}`
- **404** unknown slug · **503** busy (retry after `Retry-After`) · **5xx** upstream failure or timeout (retry with backoff).

## Notes

- Locked into the cursor: `sort_option`, `enrich_buyer_profiles`, `include_subratings`. Set them on the first call; later pages reuse them.

## Related

- [Etsy Product Info by Url](https://docs.scrapier.io/api-reference/etsy/etsy-product-info-by-url.md): Structured Etsy data: send `urls`. Single lookup, 1 credit per successful call.
- [Etsy Search by Keyword](https://docs.scrapier.io/api-reference/etsy/etsy-search-by-keyword.md): Structured Etsy data: send `queries`. Cursor-paginated, 1 credit per successful call.
- [Etsy Search Suggestions](https://docs.scrapier.io/api-reference/etsy/etsy-search-suggestions.md): Structured Etsy data: send `queries`. Cursor-paginated, 1 credit per successful call.
- [Etsy Shop Products](https://docs.scrapier.io/api-reference/etsy/etsy-shop-products.md): Structured Etsy data: send `urls`. Cursor-paginated, 1 credit per successful call.
