> 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`.

# AliExpress Reviews

Structured AliExpress data: send `product_id`. Cursor-paginated, 1 credit per successful call.

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

## Overview

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

## Request

```bash
curl -G "https://api.scrapier.io/api/v2/aliexpress-reviews/" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "product_id=1005006079931969" \
  --max-time 210
```

```python
import requests

resp = requests.get(
    "https://api.scrapier.io/api/v2/aliexpress-reviews/",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"product_id": "1005006079931969"},
    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. |
| `product_id` | string | yes | e.g. `1005006079931969` | AliExpress product id or full product URL. Required first call. Aliases: product_ids, url, urls. |
| `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. |
| `filter` | string | no | `all` | all \| 1-5 \| image \| additional \| local. One of: `all`, `1`, `2`, `3`, `4`, `5`, `image`, `additional`, `local`. Locked in cursor. |
| `sort` | string | no | `default` | default \| newest. One of: `default`, `newest`. Locked in cursor. |
| `country` | string | no | `US` | Reviewer country for filter=local. Locked in cursor. |
| `lang` | string | no | `EN` | Translation language ISO code (EN RU PT ES FR ...). Locked in cursor. |
| `label` | string | no | `issue` | sentiment, issue, reports \| none. Locked in cursor. |
| `reports` | string | no | — | Text for label=reports. Locked in cursor. |
| `written_only` | boolean | no | `true` | Drop rating-only rows. 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": {
    "product_id": "1005006079931969",
    "page": 1,
    "page_size": 20,
    "total_pages": 61,
    "total_reviews": 1210,
    "product": {
      "id": "1005006079931969",
      "url": "https://www.aliexpress.com/item/1005006079931969.html",
      "average_rating": 4.7,
      "positive_rate": 93.6,
      "rating_counts": {
        "1": 41,
        "2": 12,
        "3": 24,
        "4": 90,
        "5": 1043
      },
      "filter_counts": {
        "additional": 35,
        "local": 42,
        "with_personal": 0,
        "image": 174,
        "all": 1207
      }
    },
    "reviews": [
      {
        "review_id": "60094073811250400",
        "id": "60094073811250400",
        "entity_id": "1005006079931969",
        "url": "https://www.aliexpress.com/item/1005006079931969.html#nav-review",
        "title": "It has the same audio quality as my old Audio Technica headphones, paid 100€ for them 6 years ago.",
        "text": "It has the same audio quality as my old Audio Technica headphones, paid 100€ for them 6 years ago. \n A good quality with noise reduction that is effective. \n On the plane, the noise is reduced by half. The constant noise is significantly reduced, which is what I was looking for. \n To see the durability of the headphones over time.",
        "rating": {
          "value": 5,
          "max": 5
        },
        "author": {
          "name": "F***u",
          "avatar_url": "https://ae-pic-a1.aliexpress-media.com/kf/UTB8DtA7ASnEXKJk43Ubq6zLppXa9.jpg_220x220.jpg",
          "url": null,
          "location": "US",
          "reviews_count": null
        },
        "helpful_votes": 0,
        "verified": true,
        "source": "aliexpress",
        "language": "EN",
        "original_language": "EN",
        "translated": true,
        "images": [
          "https://ae-pic-a1.aliexpress-media.com/kf/S92988cb8a01340d895866c58fccff6d8F.jpg"
        ],
        "variant": "Color:MA10s Ships From:China Mainland",
        "responses": [],
        "published_at": "2025-11-29T00:00:00.000Z",
        "product_id": "1005006079931969",
        "product_url": "https://www.aliexpress.com/item/1005006079931969.html",
        "product_average_rating": 4.7,
        "product_total_reviews": 1210,
        "computed": {
          "labels": {
            "sentiment": {
              "level": 4,
              "score_0_1": 0.98,
              "confidence": 0.9,
              "rating_mismatch": false
            },
            "issue": {
              "label": "none",
              "confidence": 0.99
            }
          }
        },
        "input_product": "1005006079931969",
        "page": 1,
        "position": 1,
        "scraped_at": "2026-09-26T11:07:46.720Z"
      },
      {
        "review_id": "60097526755958546",
        "id": "60097526755958546",
        "entity_id": "1005006079931969",
        "url": "https://www.aliexpress.com/item/1005006079931969.html#nav-review",
        "title": "Excellent sound quality, considering the affordable price, reminiscent of a JBL TWS earphone I own.",
        "text": "Excellent sound quality, considering the affordable price, reminiscent of a JBL TWS earphone I own. The finish is very good, looking sturdy. There's a bit more \"black piano\" on the case that I don't like; it's likely to scratch easily. The fit is excellent, with several shape options available.",
        "rating": {
          "value": 5,
          "max": 5
        },
        "author": {
          "name": "A***s",
          "avatar_url": "https://ae-pic-a1.aliexpress-media.com/kf/Ab5960cf82a9949efa88b2637789b5c423.jpg_220x220.jpg",
          "url": null,
          "location": "US",
          "reviews_count": null
        },
        "helpful_votes": 0,
        "verified": true,
        "source": "aliexpress",
        "language": "EN",
        "original_language": "EN",
        "translated": true,
        "images": [
          "https://ae-pic-a1.aliexpress-media.com/kf/A4f6696d532f64501922f1d4f13ee17414.jpg",
          "https://ae-pic-a1.aliexpress-media.com/kf/A853f690bcbd24a8bbe9828de509b5b49D.jpg"
        ],
        "variant": "Color:MA10 pro Ships From:China Mainland",
        "responses": [],
        "published_at": "2026-06-18T00:00:00.000Z",
        "product_id": "1005006079931969",
        "product_url": "https://www.aliexpress.com/item/1005006079931969.html",
        "product_average_rating": 4.7,
        "product_total_reviews": 1210,
        "computed": {
          "labels": {
            "sentiment": {
              "level": 4,
              "score_0_1": 0.94,
              "confidence": 0.99,
              "rating_mismatch": false
            },
            "issue": {
              "label": "poor_quality",
              "confidence": 0.81
            }
          }
        },
        "input_product": "1005006079931969",
        "page": 1,
        "position": 2,
        "scraped_at": "2026-09-26T11:07:46.720Z"
      }
    ],
    "next_cursor": "eyJpIjoiIiwibGsiOnt9LCJwIjoyLCJwaWQiOiIxMDA1MDA2MDc5OTMxOTY5IiwicyI6WyI2MDA5NDA3MzgxMTI1MDQwMCIsIjYwMDk3NTI2NzU1OTU4NTQ2IiwiNjAwOTc0MjUzNzIyMDgyNzMiLCI2MDA5NDQ3NDc5NzExMjE2MSIsIjYwMDkzNjU3NjY1ODY3MjkyIiwiNTAyMDYxMjg4NDQ5MDUzNTQiLCI2MDA5NzAxMDk1MTI4NjY1MCIsIjMwMTAwNjgzNzcwOTMwNTY0IiwiNjAwOTQxNDM0MzA5ODM1NjYiLCI2MDA5NDUwNDM3MjE1NDU5MiIsIjYwMDk2Mzg5MjY1MjIxMzkwIiwiNjAwOTM4NDAzMjEzMTQzMTEiLCI2MDA5ODMxNzIxNzUxMTc4NyIsIjYwMDkzOTQxMzA2Njg3MDAwIiwiNjAwOTMwMDc4NjIyNjQzODYiLCI2MDA5Nzg5NjQ4ODUwNzk4NCIsIjMwMDk4OTk2NjM3MzYxMzEzIiwiNjAwOTI5NTc1OTc2NjQzODYiLCI2MDA5Njk4Nzg2NDkyNzU2MCIsIjYwMDk0NTcyMjA2NTEzODI5Il19"
  }
}
```

## Response fields

| Field | Type | Example | Description |
|---|---|---|---|
| `product_id` | string | `1005006079931969` |  |
| `page` | integer | `1` |  |
| `page_size` | integer | `20` |  |
| `total_pages` | integer | `61` |  |
| `total_reviews` | integer | `1210` |  |
| `product` | object | `{…}` |  |
| `reviews` | array | `[2 items]` | The results. |
| `next_cursor` | string | `eyJpIjoiIiwibGsiOnt9LCJwIjoyLCJwaWQiOiIxMDA1M…` | Pass back as `cursor` for the next page. `null` on the last page. |
| `reviews[].review_id` | string | `60094073811250400` |  |
| `reviews[].id` | string | `60094073811250400` |  |
| `reviews[].entity_id` | string | `1005006079931969` |  |
| `reviews[].url` | string | `https://www.aliexpress.com/item/1005006079931…` |  |
| `reviews[].title` | string | `It has the same audio quality as my old Audio…` |  |
| `reviews[].text` | string | `It has the same audio quality as my old Audio…` |  |
| `reviews[].rating` | object | `{…}` |  |
| `reviews[].author` | object | `{…}` |  |
| `reviews[].helpful_votes` | integer | `0` |  |
| `reviews[].verified` | boolean | `true` |  |
| `reviews[].source` | string | `aliexpress` |  |
| `reviews[].language` | string | `EN` |  |
| `reviews[].original_language` | string | `EN` |  |
| `reviews[].translated` | boolean | `true` |  |
| `reviews[].images` | array | `[1 item]` |  |
| `reviews[].variant` | string | `Color:MA10s Ships From:China Mainland` |  |
| `reviews[].responses` | array | `[]` |  |
| `reviews[].published_at` | string | `2025-11-29T00:00:00.000Z` |  |
| `reviews[].product_id` | string | `1005006079931969` |  |
| `reviews[].product_url` | string | `https://www.aliexpress.com/item/1005006079931…` |  |
| `reviews[].product_average_rating` | number | `4.7` |  |
| `reviews[].product_total_reviews` | integer | `1210` |  |
| `reviews[].computed` | object | `{…}` |  |
| `reviews[].input_product` | string | `1005006079931969` |  |
| `reviews[].page` | integer | `1` |  |
| `reviews[].position` | integer | `1` |  |
| `reviews[].scraped_at` | string | `2026-09-26T11:07:46.720Z` |  |

## 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/aliexpress-reviews/"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
params = {"product_id": "1005006079931969"}
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: `filter`, `sort`, `country`, `lang`, `label`, `reports`, `written_only`. Set them on the first call; later pages reuse them.
- This endpoint can take several minutes. Set your client timeout to at least 210 seconds.

## Related

- [AliExpress Products](https://docs.scrapier.io/api-reference/aliexpress/aliexpress-products.md): Structured AliExpress data: send `queries`. Cursor-paginated, 1 credit per successful call.
